From f0bca7e69f8de59b9b9e6e247f960095c99c0f62 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 2 Jun 2023 12:41:04 +0000 Subject: [PATCH 001/143] Transform error messages --- lib/main.js | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/main.js b/lib/main.js index 854bea0..5864149 100644 --- a/lib/main.js +++ b/lib/main.js @@ -23,7 +23,7 @@ var isString = require( '@stdlib/assert-is-string' ).isPrimitive; var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // MAIN // @@ -64,14 +64,14 @@ var format = require( '@stdlib/string-format' ); function first( str, n ) { var nextBreak; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } if ( str.length === 0 ) { return ''; } if ( arguments.length > 1 ) { if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } if ( str.length <= n ) { return str; diff --git a/package.json b/package.json index 0a45204..3cd232d 100644 --- a/package.json +++ b/package.json @@ -48,7 +48,7 @@ "@stdlib/process-read-stdin": "^0.0.7", "@stdlib/regexp-eol": "^0.0.7", "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", "@stdlib/utils-regexp-from-string": "^0.0.9" }, From ec46cec3649c8a0987389647bfa00242ed8fe732 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 2 Jun 2023 12:42:20 +0000 Subject: [PATCH 002/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 124 +- benchmark/benchmark.js | 55 - bin/cli | 114 - branches.md | 57 - docs/repl.txt | 29 - docs/types/test.ts | 55 - docs/usage.txt | 9 - etc/cli_opts.json | 18 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 97 - package.json | 69 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 305 - test/test.js | 153 - 42 files changed, 6196 insertions(+), 4647 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -223,7 +123,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 935947d..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,55 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2021 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index 957e65a..0000000 --- a/bin/cli +++ /dev/null @@ -1,114 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - console.log( first( args[ 0 ], n ) ); // eslint-disable-line no-console - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - for ( i = 0; i < lines.length; i++ ) { - console.log( first( lines[ i ], n ) ); // eslint-disable-line no-console - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index c15ce28..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,29 +0,0 @@ - -{{alias}}( str[, n] ) - Returns the first visual character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - Returns - ------- - out: string - Updated string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop' ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 6f8699e..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,55 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2019 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a value other than a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided a second argument that is not a number... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', 'abc' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', {} ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided insufficient arguments... -{ - first(); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index e475235..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,9 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 5d6ecc9..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index 8f2fed0..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..bb1f984 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!e(i))throw new TypeError(s("null3R",i));if(0===i.length)return"";if(arguments.length>1){if(!r(n))throw new TypeError(s("null3k",n));if(i.length<=n)return i;for(m=0;n>0;)m=t(i,m),n-=1}else m=t(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..b62358e --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2018 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( str.length === 0 ) {\n\t\treturn '';\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tif ( str.length <= n ) {\n\t\t\treturn str;\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// If `nextBreak` equals -1, it means that `str` is a string with a single grapheme cluster. In that case, we return `str` itself:\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","length","arguments","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAoB,IAAfA,EAAIM,OACR,MAAO,GAER,GAAKC,UAAUD,OAAS,EAAI,CAC3B,IAAME,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAExC,GAAKD,EAAIM,QAAUL,EAClB,OAAOD,EAGR,IADAE,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dcdf01f..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first visual character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 5864149..0000000 --- a/lib/main.js +++ /dev/null @@ -1,97 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// MAIN // - -/** -* Returns the first visual character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @throws {TypeError} must provide a string -* @throws {TypeError} second argument must be a nonnegative integer -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str, n ) { - var nextBreak; - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - if ( str.length === 0 ) { - return ''; - } - if ( arguments.length > 1 ) { - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - if ( str.length <= n ) { - return str; - } - nextBreak = 0; - while ( n > 0 ) { - nextBreak = nextGraphemeClusterBreak( str, nextBreak ); - n -= 1; - } - } else { - nextBreak = nextGraphemeClusterBreak( str ); - } - // If `nextBreak` equals -1, it means that `str` is a string with a single grapheme cluster. In that case, we return `str` itself: - if ( str === '' || nextBreak === -1 ) { - return str; - } - return str.substring( 0, nextBreak ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3cd232d..3cd8740 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first visual character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,45 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..a4e6e16 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 0c1476f..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 288dc67..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,305 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 679ee76..0000000 --- a/test/test.js +++ /dev/null @@ -1,153 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2018 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns empty string' ); - t.end(); -}); - -tape( 'the function returns the first character of a given string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns first character' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns first character' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns first character' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns the empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns empty string' ); - - t.end(); -}); - -tape( 'the function returns the first `n` visual characters of a given string if provided a second argument', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns first character' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns first character' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); From 8ca3a906c8f6b06da325cf1f6c3847298faf3778 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 29 Jun 2023 01:13:19 +0000 Subject: [PATCH 003/143] Transform error messages --- lib/main.js | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/main.js b/lib/main.js index 405ef69..51aa470 100644 --- a/lib/main.js +++ b/lib/main.js @@ -23,7 +23,7 @@ var isString = require( '@stdlib/assert-is-string' ).isPrimitive; var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // MAIN // @@ -64,11 +64,11 @@ var format = require( '@stdlib/string-format' ); function first( str, n ) { var nextBreak; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } if ( arguments.length > 1 ) { if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } nextBreak = 0; while ( n > 0 ) { diff --git a/package.json b/package.json index 0a45204..3cd232d 100644 --- a/package.json +++ b/package.json @@ -48,7 +48,7 @@ "@stdlib/process-read-stdin": "^0.0.7", "@stdlib/regexp-eol": "^0.0.7", "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", "@stdlib/utils-regexp-from-string": "^0.0.9" }, From 7554b71c81bda1cb3408ecf1eba5eb3445cc8775 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 29 Jun 2023 01:13:51 +0000 Subject: [PATCH 004/143] Remove files --- index.d.ts | 57 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6239 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 68d8f2e..0000000 --- a/index.d.ts +++ /dev/null @@ -1,57 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2019 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -/** -* Removes the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to remove (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index bb1f984..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!e(i))throw new TypeError(s("null3R",i));if(0===i.length)return"";if(arguments.length>1){if(!r(n))throw new TypeError(s("null3k",n));if(i.length<=n)return i;for(m=0;n>0;)m=t(i,m),n-=1}else m=t(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index b62358e..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2018 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( str.length === 0 ) {\n\t\treturn '';\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tif ( str.length <= n ) {\n\t\t\treturn str;\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// If `nextBreak` equals -1, it means that `str` is a string with a single grapheme cluster. In that case, we return `str` itself:\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","length","arguments","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAoB,IAAfA,EAAIM,OACR,MAAO,GAER,GAAKC,UAAUD,OAAS,EAAI,CAC3B,IAAME,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAExC,GAAKD,EAAIM,QAAUL,EAClB,OAAOD,EAGR,IADAE,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index a4e6e16..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From e63266e805ab5264aae0086dde77e7e969ec95c1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 29 Jun 2023 01:14:38 +0000 Subject: [PATCH 005/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 124 +- benchmark/benchmark.js | 55 - bin/cli | 114 - branches.md | 57 - docs/repl.txt | 29 - docs/types/test.ts | 55 - docs/usage.txt | 9 - etc/cli_opts.json | 18 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 91 - package.json | 69 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 305 - test/test.js | 153 - 42 files changed, 6196 insertions(+), 4641 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -223,7 +123,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 27eb310..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,55 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index 5a02efa..0000000 --- a/bin/cli +++ /dev/null @@ -1,114 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - console.log( first( args[ 0 ], n ) ); // eslint-disable-line no-console - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - for ( i = 0; i < lines.length; i++ ) { - console.log( first( lines[ i ], n ) ); // eslint-disable-line no-console - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index c15ce28..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,29 +0,0 @@ - -{{alias}}( str[, n] ) - Returns the first visual character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - Returns - ------- - out: string - Updated string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop' ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 867862c..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,55 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a value other than a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided a second argument that is not a number... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', 'abc' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', {} ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided insufficient arguments... -{ - first(); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index e475235..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,9 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 5d6ecc9..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..6bc5c20 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!s(i))throw new TypeError(t("null3R",i));if(arguments.length>1){if(!e(n))throw new TypeError(t("null3k",n));for(m=0;n>0;)m=r(i,m),n-=1}else m=r(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..3a3ecfe --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster...\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","arguments","length","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAKM,UAAUC,OAAS,EAAI,CAC3B,IAAMC,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAGxC,IADAC,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 5fb605d..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first visual character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 51aa470..0000000 --- a/lib/main.js +++ /dev/null @@ -1,91 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// MAIN // - -/** -* Returns the first visual character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @throws {TypeError} must provide a string -* @throws {TypeError} second argument must be a nonnegative integer -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str, n ) { - var nextBreak; - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - if ( arguments.length > 1 ) { - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - nextBreak = 0; - while ( n > 0 ) { - nextBreak = nextGraphemeClusterBreak( str, nextBreak ); - n -= 1; - } - } else { - nextBreak = nextGraphemeClusterBreak( str ); - } - // Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster... - if ( str === '' || nextBreak === -1 ) { - return str; - } - return str.substring( 0, nextBreak ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3cd232d..3cd8740 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first visual character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,45 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..0a89098 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index eb77440..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,305 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 7c11ab6..0000000 --- a/test/test.js +++ /dev/null @@ -1,153 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns empty string' ); - t.end(); -}); - -tape( 'the function returns the first visual character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` visual characters of a provided string', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); From 67bfcdcf52ce5f9476fdefe3506cdc1c9430dcbe Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 1 Jul 2023 05:45:22 +0000 Subject: [PATCH 006/143] Transform error messages --- lib/main.js | 6 +++--- package.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/main.js b/lib/main.js index 405ef69..51aa470 100644 --- a/lib/main.js +++ b/lib/main.js @@ -23,7 +23,7 @@ var isString = require( '@stdlib/assert-is-string' ).isPrimitive; var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // MAIN // @@ -64,11 +64,11 @@ var format = require( '@stdlib/string-format' ); function first( str, n ) { var nextBreak; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } if ( arguments.length > 1 ) { if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } nextBreak = 0; while ( n > 0 ) { diff --git a/package.json b/package.json index 0a45204..3cd232d 100644 --- a/package.json +++ b/package.json @@ -48,7 +48,7 @@ "@stdlib/process-read-stdin": "^0.0.7", "@stdlib/regexp-eol": "^0.0.7", "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", "@stdlib/utils-regexp-from-string": "^0.0.9" }, From 1b5dbf14e51ccfba66b173e8e85281ba3ba9fb79 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 1 Jul 2023 13:25:58 +0000 Subject: [PATCH 007/143] Remove files --- index.d.ts | 57 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6239 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 4d5da1b..0000000 --- a/index.d.ts +++ /dev/null @@ -1,57 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -/** -* Removes the first visual character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 6bc5c20..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!s(i))throw new TypeError(t("null3R",i));if(arguments.length>1){if(!e(n))throw new TypeError(t("null3k",n));for(m=0;n>0;)m=r(i,m),n-=1}else m=r(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 3a3ecfe..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster...\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","arguments","length","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAKM,UAAUC,OAAS,EAAI,CAC3B,IAAMC,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAGxC,IADAC,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 0a89098..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From f23a0293a9790fcb58d93cd1bb3fbc4dee952abb Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 1 Jul 2023 13:26:44 +0000 Subject: [PATCH 008/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 124 +- benchmark/benchmark.js | 55 - bin/cli | 114 - branches.md | 57 - docs/repl.txt | 29 - docs/types/test.ts | 55 - docs/usage.txt | 9 - etc/cli_opts.json | 18 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 91 - package.json | 69 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 305 - test/test.js | 153 - 43 files changed, 6196 insertions(+), 4642 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index fb0e82b..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2023-07-01T03:43:03.668Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -223,7 +123,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 27eb310..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,55 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index 5a02efa..0000000 --- a/bin/cli +++ /dev/null @@ -1,114 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - console.log( first( args[ 0 ], n ) ); // eslint-disable-line no-console - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - for ( i = 0; i < lines.length; i++ ) { - console.log( first( lines[ i ], n ) ); // eslint-disable-line no-console - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index c15ce28..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,29 +0,0 @@ - -{{alias}}( str[, n] ) - Returns the first visual character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - Returns - ------- - out: string - Updated string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop' ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 867862c..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,55 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a value other than a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided a second argument that is not a number... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', 'abc' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', {} ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError -} - -// The compiler throws an error if the function is provided insufficient arguments... -{ - first(); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index e475235..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,9 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 5d6ecc9..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..6bc5c20 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!s(i))throw new TypeError(t("null3R",i));if(arguments.length>1){if(!e(n))throw new TypeError(t("null3k",n));for(m=0;n>0;)m=r(i,m),n-=1}else m=r(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..3a3ecfe --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster...\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","arguments","length","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAKM,UAAUC,OAAS,EAAI,CAC3B,IAAMC,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAGxC,IADAC,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 5fb605d..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first visual character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 51aa470..0000000 --- a/lib/main.js +++ /dev/null @@ -1,91 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var nextGraphemeClusterBreak = require( '@stdlib/string-next-grapheme-cluster-break' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// MAIN // - -/** -* Returns the first visual character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @throws {TypeError} must provide a string -* @throws {TypeError} second argument must be a nonnegative integer -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str, n ) { - var nextBreak; - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - if ( arguments.length > 1 ) { - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - nextBreak = 0; - while ( n > 0 ) { - nextBreak = nextGraphemeClusterBreak( str, nextBreak ); - n -= 1; - } - } else { - nextBreak = nextGraphemeClusterBreak( str ); - } - // Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster... - if ( str === '' || nextBreak === -1 ) { - return str; - } - return str.substring( 0, nextBreak ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3cd232d..3cd8740 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first visual character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,45 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/string-next-grapheme-cluster-break": "^0.0.9", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..622f79a --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index eb77440..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,305 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 7c11ab6..0000000 --- a/test/test.js +++ /dev/null @@ -1,153 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns empty string' ); - t.end(); -}); - -tape( 'the function returns the first visual character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` visual characters of a provided string', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); From a6059ec54791542f9d543cfab1a5809aad7b7f54 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 14 Jul 2023 23:41:05 +0000 Subject: [PATCH 009/143] Transform error messages --- lib/main.js | 10 +++++----- package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..d9c7a39 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } opts = { 'mode': 'grapheme' @@ -102,16 +102,16 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( 'null2h', options ) ); } } if ( options ) { diff --git a/package.json b/package.json index 37154ea..e5f6a74 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/utils-regexp-from-string": "^0.0.9" }, "devDependencies": { From 38818f6cd1466f9a54cd8d4388fed9f713939d0f Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 14 Jul 2023 23:42:04 +0000 Subject: [PATCH 010/143] Remove files --- index.d.ts | 57 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6239 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 4d5da1b..0000000 --- a/index.d.ts +++ /dev/null @@ -1,57 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -/** -* Removes the first visual character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 6bc5c20..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/string-next-grapheme-cluster-break@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";function i(i,n){var m;if(!s(i))throw new TypeError(t("null3R",i));if(arguments.length>1){if(!e(n))throw new TypeError(t("null3k",n));for(m=0;n>0;)m=r(i,m),n-=1}else m=r(i);return""===i||-1===m?i:i.substring(0,m)}export{i as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 3a3ecfe..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport nextGraphemeClusterBreak from '@stdlib/string-next-grapheme-cluster-break';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// MAIN //\n\n/**\n* Returns the first visual character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @throws {TypeError} must provide a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str, n ) {\n\tvar nextBreak;\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\tif ( arguments.length > 1 ) {\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\tnextBreak = 0;\n\t\twhile ( n > 0 ) {\n\t\t\tnextBreak = nextGraphemeClusterBreak( str, nextBreak );\n\t\t\tn -= 1;\n\t\t}\n\t} else {\n\t\tnextBreak = nextGraphemeClusterBreak( str );\n\t}\n\t// Value of `nextBreak` will be -1 if and only if `str` is an empty string or `str` has only 1 extended grapheme cluster...\n\tif ( str === '' || nextBreak === -1 ) {\n\t\treturn str;\n\t}\n\treturn str.substring( 0, nextBreak );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["first","str","n","nextBreak","isString","TypeError","format","arguments","length","isNonNegativeInteger","nextGraphemeClusterBreak","substring"],"mappings":";;0ZA+DA,SAASA,EAAOC,EAAKC,GACpB,IAAIC,EACJ,IAAMC,EAAUH,GACf,MAAM,IAAII,UAAWC,EAAQ,SAAUL,IAExC,GAAKM,UAAUC,OAAS,EAAI,CAC3B,IAAMC,EAAsBP,GAC3B,MAAM,IAAIG,UAAWC,EAAQ,SAAUJ,IAGxC,IADAC,EAAY,EACJD,EAAI,GACXC,EAAYO,EAA0BT,EAAKE,GAC3CD,GAAK,CAER,MACEC,EAAYO,EAA0BT,GAGvC,MAAa,KAARA,IAA6B,IAAfE,EACXF,EAEDA,EAAIU,UAAW,EAAGR,EAC1B"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 622f79a..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 1a4e13f6f96d5f07302798ca6419a4fcd4c0f5fd Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 14 Jul 2023 23:42:59 +0000 Subject: [PATCH 011/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - docs/repl.txt | 47 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 379 -- 42 files changed, 6196 insertions(+), 5179 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index c7ee545..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,47 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - units. - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..a91f785 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..44f57e3 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index d9c7a39..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'null2h', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index e5f6a74..1803529 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "github:stdlib-js/array-base-assert-contains#main", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", - "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", - "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..12d4c97 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index b9d5c20..0000000 --- a/test/test.js +++ /dev/null @@ -1,379 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 84e67c41dba39fa1af04c76e0980ea0cdf5ceac9 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 15 Jul 2023 23:57:58 +0000 Subject: [PATCH 012/143] Transform error messages --- lib/main.js | 10 +++++----- package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..d9c7a39 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } opts = { 'mode': 'grapheme' @@ -102,16 +102,16 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( 'null2h', options ) ); } } if ( options ) { diff --git a/package.json b/package.json index 37154ea..e5f6a74 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/utils-regexp-from-string": "^0.0.9" }, "devDependencies": { From 81da29d7b8fe4212183bd4c9cd51ea417275f371 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 15 Jul 2023 23:58:28 +0000 Subject: [PATCH 013/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index acb72b0..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code units. - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index a91f785..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 44f57e3..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 12d4c97..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 4f39f91f54c64cf5291a510f2e2b9e648e64d3e2 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 15 Jul 2023 23:59:28 +0000 Subject: [PATCH 014/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - docs/repl.txt | 47 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 42 files changed, 6196 insertions(+), 5206 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index c7ee545..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,47 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - units. - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..a91f785 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..44f57e3 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index d9c7a39..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'null2h', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index e5f6a74..1803529 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "github:stdlib-js/array-base-assert-contains#main", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", - "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", - "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..cfcce9c --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 58e7f686e2b1d39e175549a9a89f147e36fff567 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 16 Jul 2023 00:00:35 +0000 Subject: [PATCH 015/143] Transform error messages --- lib/main.js | 10 +++++----- package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..d9c7a39 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } opts = { 'mode': 'grapheme' @@ -102,16 +102,16 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( 'null2h', options ) ); } } if ( options ) { diff --git a/package.json b/package.json index 37154ea..e5f6a74 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/utils-regexp-from-string": "^0.0.9" }, "devDependencies": { From 767673511c207f302f95a71391bcb2f1bfeb53c6 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 16 Jul 2023 00:01:07 +0000 Subject: [PATCH 016/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index acb72b0..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code units. - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index a91f785..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 44f57e3..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index cfcce9c..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From c967d8177c9d2412dce744e13aacefd5e24d6ece Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 16 Jul 2023 00:02:04 +0000 Subject: [PATCH 017/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - docs/repl.txt | 47 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 42 files changed, 6196 insertions(+), 5206 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index bee089b..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,47 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit. - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..a91f785 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..44f57e3 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index d9c7a39..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'null2h', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index e5f6a74..1803529 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "github:stdlib-js/array-base-assert-contains#main", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", - "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", - "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..213850f --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From fac251f0df1ba5d07181dad6852d7c8567b4d002 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 18 Jul 2023 21:56:19 +0000 Subject: [PATCH 018/143] Transform error messages --- lib/main.js | 10 +++++----- package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..d9c7a39 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } opts = { 'mode': 'grapheme' @@ -102,16 +102,16 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( 'null2h', options ) ); } } if ( options ) { diff --git a/package.json b/package.json index 37154ea..e5f6a74 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/utils-regexp-from-string": "^0.0.9" }, "devDependencies": { From d1cbaad4c340a98fbb313ed230b9b9b07cd7814d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 18 Jul 2023 21:56:52 +0000 Subject: [PATCH 019/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2cfae96..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit. - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index a91f785..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 44f57e3..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;62BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 213850f..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From dce2e49ed48366e379ad193e7b29b3c7a6417194 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 18 Jul 2023 21:57:46 +0000 Subject: [PATCH 020/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 42 files changed, 6196 insertions(+), 5207 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 240c5f2..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v1 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..51f2689 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.0.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..bba6f36 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;o3BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index d9c7a39..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'null2h', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index e5f6a74..1803529 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "github:stdlib-js/array-base-assert-contains#main", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "github:stdlib-js/string-base-first#main", - "@stdlib/string-base-first-code-point": "github:stdlib-js/string-base-first-code-point#main", - "@stdlib/string-base-first-grapheme-cluster": "github:stdlib-js/string-base-first-grapheme-cluster#main", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..93b8efd --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 43634a4ad8ed391fd160f1ec18a6d12692540753 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Jul 2023 15:12:35 +0000 Subject: [PATCH 021/143] Transform error messages --- lib/main.js | 10 +++++----- package.json | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..d9c7a39 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( 'null3R', str ) ); } opts = { 'mode': 'grapheme' @@ -102,16 +102,16 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( 'null3k', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( 'null2h', options ) ); } } if ( options ) { diff --git a/package.json b/package.json index 1b47b8a..5ee4ffe 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.0.1", "@stdlib/string-base-first-code-point": "^0.0.1", "@stdlib/string-base-first-grapheme-cluster": "^0.0.1", - "@stdlib/string-format": "^0.0.3", + "@stdlib/error-tools-fmtprodmsg": "^0.0.2", "@stdlib/utils-regexp-from-string": "^0.0.9" }, "devDependencies": { From fb9d9fe6f490452ca77dbb11f588ba4e666e58b1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Jul 2023 15:13:05 +0000 Subject: [PATCH 022/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2dacfdf..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 2.0 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 51f2689..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.0.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index bba6f36..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;o3BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 93b8efd..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From a3988ef1d0487ecf978c7b7e0ff8969474dede24 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Jul 2023 15:13:46 +0000 Subject: [PATCH 023/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 1007 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 42 files changed, 6196 insertions(+), 5207 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 952a131..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1007 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Format error messages: - - name: 'Replace double quotes with single quotes in rewritten format string error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\( \"([a-zA-Z0-9]+)\"/Error\( format\( '\1'/g" {} \; - - # Format string literal error messages: - - name: 'Replace double quotes with single quotes in rewritten string literal error messages' - run: | - find . -name "*.js" -exec sed -E -i "s/Error\( format\(\"([a-zA-Z0-9]+)\"\)/Error\( format\( '\1' \)/g" {} \; - - # Format code: - - name: 'Replace double quotes with single quotes in inserted `require` calls' - run: | - find . -name "*.js" -exec sed -E -i "s/require\( ?\"@stdlib\/error-tools-fmtprodmsg\" ?\);/require\( '@stdlib\/error-tools-fmtprodmsg' \);/g" {} \; - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v2 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..4373dcf --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.0.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.0.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.0.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.0.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var l=["grapheme","code_point","code_unit"],p={grapheme:d,code_point:n,code_unit:o},h=i(l);function j(i){var o,n,d,j;if(!e(i))throw new TypeError(m("null3R",i));if(d={mode:"grapheme"},1===(n=arguments.length))j=1;else if(2===n){if(t(j=arguments[1]))o=j,j=1;else if(!s(j))throw new TypeError(m("null3k",j))}else{if(!s(j=arguments[1]))throw new TypeError(m("null3k",j));if(!t(o=arguments[2]))throw new TypeError(m("null2h",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!h(d.mode)))throw new TypeError(m('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",l.join('", "'),d.mode));return p[d.mode](i,j)}export{j as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..8944881 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'null3R', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'null3k', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'null2h', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;y4BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,SAAUP,IAMxC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,SAAUH,QAElC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,SAAUH,IAGxC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,SAAUN,GAExC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index d9c7a39..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'null3R', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'null3k', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'null2h', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5ee4ffe..8fdb775 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.0.1", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "^0.0.1", - "@stdlib/string-base-first-code-point": "^0.0.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.0.1", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..c4f187c --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 2fa1344dcd4233b8c86d42ef728d36fdb3661f3b Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Jul 2023 15:14:45 +0000 Subject: [PATCH 024/143] Update README.md for ESM bundle v0.0.1 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ce6ceb..7203ac6 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.0.1-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -95,7 +95,7 @@ out = first( 'foo bar', 10 ); - - - - From 1d0e33bff9800f93ee335724aca718cd253de23d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 19 Aug 2023 00:56:14 +0000 Subject: [PATCH 028/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 992 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 45 files changed, 6196 insertions(+), 5207 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 0fd4d6c..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index b61e587..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,992 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v2 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -247,7 +146,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..00e6ee5 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.0.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.0.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.0.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.0.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..d186467 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;y4BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5ee4ffe..8fdb775 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.0.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.0.1", - "@stdlib/assert-has-own-property": "^0.0.7", - "@stdlib/assert-is-nonnegative-integer": "^0.0.7", - "@stdlib/assert-is-plain-object": "^0.0.7", - "@stdlib/assert-is-regexp-string": "^0.0.9", - "@stdlib/assert-is-string": "^0.0.8", - "@stdlib/cli-ctor": "^0.0.3", - "@stdlib/fs-read-file": "^0.0.8", - "@stdlib/process-read-stdin": "^0.0.7", - "@stdlib/regexp-eol": "^0.0.7", - "@stdlib/streams-node-stdin": "^0.0.7", - "@stdlib/string-base-first": "^0.0.1", - "@stdlib/string-base-first-code-point": "^0.0.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.0.1", - "@stdlib/error-tools-fmtprodmsg": "^0.0.2", - "@stdlib/utils-regexp-from-string": "^0.0.9" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.0.8", - "@stdlib/assert-is-windows": "^0.0.7", - "@stdlib/bench": "^0.0.12", - "@stdlib/process-exec-path": "^0.0.7", - "@stdlib/string-replace": "^0.0.11", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..bfa63d2 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 2b072bf25921d832da450349396ddbf33fe9df4c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 24 Sep 2023 17:08:26 +0000 Subject: [PATCH 029/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..0732124 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F,Ex', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V,FD', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 3613763..6aa06b9 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.0", "@stdlib/string-base-first-code-point": "^0.1.0", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.0", + "@stdlib/error-tools-fmtprodmsg": "^0.1.0", "@stdlib/utils-regexp-from-string": "^0.1.0" }, "devDependencies": { From 6bbdd04ce50f6ede63496c23991395ad041487f8 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 24 Sep 2023 17:44:04 +0000 Subject: [PATCH 030/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2aa7928..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 00e6ee5..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.0.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.0.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.0.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.0.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.0.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index d186467..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;y4BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index bfa63d2..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From d35c4a535acc4565a86ca6ae420ba4a930abe0b3 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 24 Sep 2023 17:44:54 +0000 Subject: [PATCH 031/143] Auto-generated commit --- .editorconfig | 186 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 62 - .github/workflows/cancel.yml | 56 - .github/workflows/close_pull_requests.yml | 44 - .github/workflows/examples.yml | 62 - .github/workflows/npm_downloads.yml | 108 - .github/workflows/productionize.yml | 992 ---- .github/workflows/publish.yml | 242 - .github/workflows/publish_cli.yml | 165 - .github/workflows/test.yml | 97 - .github/workflows/test_bundles.yml | 180 - .github/workflows/test_coverage.yml | 123 - .github/workflows/test_install.yml | 83 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 46 files changed, 6196 insertions(+), 5242 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 13e9c39..0000000 --- a/.editorconfig +++ /dev/null @@ -1,186 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 06a9a75..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index a00dbe5..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,56 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - uses: styfle/cancel-workflow-action@0.11.0 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index 1733973..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,44 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - run: - runs-on: ubuntu-latest - steps: - - uses: superbrothers/close-pull-request@v3 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 7902a7d..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,62 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout the repository' - uses: actions/checkout@v3 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2c06540..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,108 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - uses: actions/upload-artifact@v3 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - uses: distributhor/workflow-webhook@v3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index b61e587..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,992 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - uses: actions/checkout@v3 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/checkout@v3 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - uses: act10ns/slack@v2 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - uses: actions/checkout@v3 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - uses: actions/setup-node@v3 - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..456b226 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.0-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.0-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.0.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.0-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..74ca815 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 6aa06b9..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.0", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.0", - "@stdlib/assert-is-regexp-string": "^0.1.0", - "@stdlib/assert-is-string": "^0.1.0", - "@stdlib/cli-ctor": "^0.1.0", - "@stdlib/fs-read-file": "^0.1.0", - "@stdlib/process-read-stdin": "^0.1.0", - "@stdlib/regexp-eol": "^0.1.0", - "@stdlib/streams-node-stdin": "^0.1.0", - "@stdlib/string-base-first": "^0.1.0", - "@stdlib/string-base-first-code-point": "^0.1.0", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.0", - "@stdlib/utils-regexp-from-string": "^0.1.0" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.0", - "@stdlib/assert-is-windows": "^0.1.0", - "@stdlib/bench": "^0.1.0", - "@stdlib/process-exec-path": "^0.1.0", - "@stdlib/string-replace": "^0.1.0", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..71714d1 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 2b3008f20381a560d106183e30635d61ad3083dc Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 24 Sep 2023 17:57:31 +0000 Subject: [PATCH 032/143] Update README.md for ESM bundle v0.1.0 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cfd9b3c..eb9a305 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.1.0-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -106,7 +106,7 @@ out = first( 'foo bar', 10 ); - - - - From 4b7bb59582e525a592ea9048996dce8be16057dd Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 3 Oct 2023 02:38:29 +0000 Subject: [PATCH 036/143] Auto-generated commit --- .editorconfig | 186 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1009 ---- .github/workflows/publish.yml | 247 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 406 -- test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 6196 insertions(+), 5715 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 13e9c39..0000000 --- a/.editorconfig +++ /dev/null @@ -1,186 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index ba372c7..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2023-10-01T05:30:30.860Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index ab56cca..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c1c45e7..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index a475709..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA corresponding to v3.0.3: - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 2eecd49..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1009 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..b7b84bf --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.0-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.0-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.0-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..74ca815 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 6aa06b9..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.0", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.0", - "@stdlib/assert-is-regexp-string": "^0.1.0", - "@stdlib/assert-is-string": "^0.1.0", - "@stdlib/cli-ctor": "^0.1.0", - "@stdlib/fs-read-file": "^0.1.0", - "@stdlib/process-read-stdin": "^0.1.0", - "@stdlib/regexp-eol": "^0.1.0", - "@stdlib/streams-node-stdin": "^0.1.0", - "@stdlib/string-base-first": "^0.1.0", - "@stdlib/string-base-first-code-point": "^0.1.0", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.0", - "@stdlib/utils-regexp-from-string": "^0.1.0" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.0", - "@stdlib/assert-is-windows": "^0.1.0", - "@stdlib/bench": "^0.1.0", - "@stdlib/process-exec-path": "^0.1.0", - "@stdlib/string-replace": "^0.1.0", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7902709 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index e21a757..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 539823180756ecbb3efe02c73f43c3a864cc1045 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 5 Oct 2023 20:12:09 +0000 Subject: [PATCH 037/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..0732124 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F,Ex', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V,FD', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 37eb60e..16cf069 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From f6a3ffd33673fb540b888d0827ac3d13c2df1b8d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 7 Oct 2023 03:27:13 +0000 Subject: [PATCH 038/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2aa7928..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index b7b84bf..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.0-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.0-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.0-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 74ca815..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7902709..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 5b84c5c12bc7bb3da30947837f74049c071f545a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 7 Oct 2023 03:27:56 +0000 Subject: [PATCH 039/143] Auto-generated commit --- .editorconfig | 186 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1009 ---- .github/workflows/publish.yml | 247 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 406 -- test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 47 files changed, 6196 insertions(+), 5714 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 13e9c39..0000000 --- a/.editorconfig +++ /dev/null @@ -1,186 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index ab56cca..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c1c45e7..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index a475709..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA corresponding to v3.0.3: - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 2eecd49..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1009 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..dd121e5 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..74ca815 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 16cf069..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/bench": "^0.1.0", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7b63819 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index e21a757..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From c5d219dafd64d744c3796d0e87bfcc1dfcc0398b Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Wed, 1 Nov 2023 17:55:15 +0000 Subject: [PATCH 040/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..0732124 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F,Ex', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V,FD', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 37eb60e..16cf069 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From 25ef3921e68af06230101fc699694c4766fca37e Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 3 Nov 2023 02:47:20 +0000 Subject: [PATCH 041/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2aa7928..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index dd121e5..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 74ca815..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7b63819..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 44c72c1aa072192ddd7073ba1ac29c035d5affe8 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 3 Nov 2023 02:48:05 +0000 Subject: [PATCH 042/143] Auto-generated commit --- .editorconfig | 186 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1009 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 6196 insertions(+), 5350 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 13e9c39..0000000 --- a/.editorconfig +++ /dev/null @@ -1,186 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tslint.json` files: -[tslint.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index ce41961..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2023-11-01T05:50:47.888Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index ab56cca..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c1c45e7..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index a475709..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA corresponding to v3.0.3: - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 2eecd49..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1009 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..dd121e5 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..74ca815 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 16cf069..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/bench": "^0.1.0", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..9d47d36 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 59f1007b74763b7881458cd77745c9c02f31bd3e Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 1 Dec 2023 14:03:22 +0000 Subject: [PATCH 043/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..0732124 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F,Ex', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X,F1', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V,FD', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index d035e6a..747040a 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From fa6f1dd76e4104b3eec154890e0e4ef0823e5de1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 2 Dec 2023 12:18:41 +0000 Subject: [PATCH 044/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 2aa7928..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -// tslint:disable:unified-signatures - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index dd121e5..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 74ca815..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 9d47d36..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 1fb6055d5ea1c129f726ccd81be98dabdcffc169 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 2 Dec 2023 12:19:19 +0000 Subject: [PATCH 045/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1011 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 227 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 6196 insertions(+), 5347 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index d86c704..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2023-12-01T05:55:57.958Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index ab56cca..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c1c45e7..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index a475709..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA corresponding to v3.0.3: - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 6957ebf..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1011 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA corresponding to v4.1.0 - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 16 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 6371ba1..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..dd121e5 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..74ca815 --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 0732124..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F,Ex', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X,F1', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V,FD', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpLi', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 747040a..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/bench": "^0.2.1", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..faa75e6 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From c1bf7daba5c2157d0417d082d73def673e2c49f9 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Jan 2024 08:25:05 +0000 Subject: [PATCH 046/143] Transform error messages --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a849fca..07ed8ca 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From e53c12e0feca1521b7002da91cfc0de84cd09adf Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Jan 2024 15:01:28 +0000 Subject: [PATCH 047/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index dd121e5..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2023 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.1.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F,Ex",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X,F1",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X,F1",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V,FD",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpLi","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 74ca815..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F,Ex', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X,F1', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V,FD', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpLi', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,WAAYP,IAM1C,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,WAAYH,QAEpC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,WAAYH,IAG1C,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,WAAYN,GAE1C,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index faa75e6..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 9d5593807cfd61074c603b395142fa10c8eb2ee6 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Jan 2024 15:01:50 +0000 Subject: [PATCH 048/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1011 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 228 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 125 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 6196 insertions(+), 5353 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 11fd41d..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-01-01T05:25:52.416Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 30656c4..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c92f5c4..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index aa0ab13..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 96d504a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1011 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -258,7 +157,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..4f2ef50 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..489b7ce --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 5971a1a..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 07ed8ca..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.1.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..69954e9 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From fdf5182737d4ba0e0e738e74d1e72da52e46d641 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 18 Jan 2024 08:15:44 +0000 Subject: [PATCH 049/143] Transform error messages --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a849fca..07ed8ca 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From a966c6996c60bdfbac421e4a984068fe41d209af Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 18 Jan 2024 08:17:14 +0000 Subject: [PATCH 050/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 4f2ef50..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 489b7ce..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 69954e9..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From c5358134dd9be7be6d5a9518fb0ea54d978c0794 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 18 Jan 2024 08:17:27 +0000 Subject: [PATCH 051/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1011 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 228 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 127 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 57 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 6197 insertions(+), 5353 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 30656c4..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c92f5c4..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index aa0ab13..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 96d504a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1011 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -263,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -333,7 +232,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index 6c22203..0000000 --- a/branches.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers. -- **deno**: [Deno][deno-url] branch for use in Deno. -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments. -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..4f2ef50 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..489b7ce --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 5971a1a..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 07ed8ca..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.1.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..2f9be5a --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 98f31ae4019c0789c34f927dda43e0d0c70511f2 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 1 Feb 2024 09:01:16 +0000 Subject: [PATCH 052/143] Transform error messages --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index a849fca..07ed8ca 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.1.1", "@stdlib/string-base-first-code-point": "^0.1.1", "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/string-format": "^0.1.1", + "@stdlib/error-tools-fmtprodmsg": "^0.1.1", "@stdlib/utils-regexp-from-string": "^0.1.1" }, "devDependencies": { From 9bdce623e18e30b739fb9d57eb0935801b883441 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 1 Feb 2024 14:22:17 +0000 Subject: [PATCH 053/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 4f2ef50..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 489b7ce..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 2f9be5a..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From ff1b10f83728ef4f69b9c776fe601ea9635c4d71 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 1 Feb 2024 14:22:39 +0000 Subject: [PATCH 054/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 128 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 228 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 6197 insertions(+), 5360 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 05cac86..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-02-01T06:19:13.659Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index 30656c4..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index 3acd3a9..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA corresponding to v0.11.0 - uses: styfle/cancel-workflow-action@b173b6ec0100793626c2d9e6b90435061f4fc3e5 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index c92f5c4..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index aa0ab13..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 303a99a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA corresponding to v3.8.1 - uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..4f2ef50 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..489b7ce --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 5971a1a..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 07ed8ca..6cd4f26 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.1.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.1.0", - "@stdlib/assert-has-own-property": "^0.1.1", - "@stdlib/assert-is-nonnegative-integer": "^0.1.0", - "@stdlib/assert-is-plain-object": "^0.1.1", - "@stdlib/assert-is-regexp-string": "^0.1.1", - "@stdlib/assert-is-string": "^0.1.1", - "@stdlib/cli-ctor": "^0.1.1", - "@stdlib/fs-read-file": "^0.1.1", - "@stdlib/process-read-stdin": "^0.1.1", - "@stdlib/regexp-eol": "^0.1.1", - "@stdlib/streams-node-stdin": "^0.1.1", - "@stdlib/string-base-first": "^0.1.1", - "@stdlib/string-base-first-code-point": "^0.1.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.1.0", - "@stdlib/error-tools-fmtprodmsg": "^0.1.1", - "@stdlib/utils-regexp-from-string": "^0.1.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.1.1", - "@stdlib/assert-is-windows": "^0.1.1", - "@stdlib/process-exec-path": "^0.1.1", - "@stdlib/string-replace": "^0.1.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.1.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..71e4cc1 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 3d062b8c8ce5cd9a000eca08642c8a0118c12856 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 15 Feb 2024 01:08:48 +0000 Subject: [PATCH 055/143] Transform error messages --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 5ab902d..9ee678b 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.0", "@stdlib/string-base-first-code-point": "^0.2.0", "@stdlib/string-base-first-grapheme-cluster": "^0.2.0", - "@stdlib/string-format": "^0.2.0", + "@stdlib/error-tools-fmtprodmsg": "^0.2.0", "@stdlib/utils-regexp-from-string": "^0.2.0" }, "devDependencies": { From ded8c682ef6f354c330fb7d22f77c71288795bdd Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 15 Feb 2024 04:33:48 +0000 Subject: [PATCH 056/143] Remove files --- index.d.ts | 118 - index.mjs | 4 - index.mjs.map | 1 - stats.html | 6177 ------------------------------------------------- 4 files changed, 6300 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 4f2ef50..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.1.1-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.1.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.1.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.1.1-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.1.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.1.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.1.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 489b7ce..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 71e4cc1..0000000 --- a/stats.html +++ /dev/null @@ -1,6177 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From c6c6445508e05921e049a83cb2ffce4daac0c76d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 15 Feb 2024 04:34:03 +0000 Subject: [PATCH 057/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ---- .github/workflows/publish.yml | 255 - .github/workflows/publish_cli.yml | 170 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 132 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 228 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 74 +- stats.html | 6177 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 6197 insertions(+), 5363 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 5098bb4..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA corresponding to v3.1.3 - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index e898b7d..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..86ae8bd --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.0-esm/index.mjs";import{isPrimitive as t}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.0-esm/index.mjs";import s from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.0-esm/index.mjs";import i from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.0-esm/index.mjs";import{factory as r}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.1.0-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.0-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.0-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-format@v0.1.1-esm/index.mjs";var a=["grapheme","code_point","code_unit"],l={grapheme:m,code_point:o,code_unit:n},p=r(a);function g(r){var n,o,m,g;if(!e(r))throw new TypeError(d("invalid argument. First argument must be a string. Value: `%s`.",r));if(m={mode:"grapheme"},1===(o=arguments.length))g=1;else if(2===o){if(s(g=arguments[1]))n=g,g=1;else if(!t(g))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g))}else{if(!t(g=arguments[1]))throw new TypeError(d("invalid argument. Second argument must be a nonnegative integer. Value: `%s`.",g));if(!s(n=arguments[2]))throw new TypeError(d("invalid argument. Options argument must be an object. Value: `%s`.",n))}if(n&&i(n,"mode")&&(m.mode=n.mode,!p(m.mode)))throw new TypeError(d('invalid option. `%s` option must be one of the following: "%s". Value: `%s`.',"mode",a.join('", "'),m.mode));return l[m.mode](r,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..489b7ce --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/string-format';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;45BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,kEAAmEP,IAMjG,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,gFAAiFH,QAEzG,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,gFAAiFH,IAG/G,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,qEAAsEN,GAEpG,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,+EAAgF,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAInJ,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 5971a1a..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 9ee678b..1eed477 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.0", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,50 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.0", - "@stdlib/assert-has-own-property": "^0.2.0", - "@stdlib/assert-is-nonnegative-integer": "^0.2.0", - "@stdlib/assert-is-plain-object": "^0.2.0", - "@stdlib/assert-is-regexp-string": "^0.2.0", - "@stdlib/assert-is-string": "^0.2.0", - "@stdlib/cli-ctor": "^0.2.0", - "@stdlib/fs-read-file": "^0.2.0", - "@stdlib/process-read-stdin": "^0.2.0", - "@stdlib/regexp-eol": "^0.2.0", - "@stdlib/streams-node-stdin": "^0.2.0", - "@stdlib/string-base-first": "^0.2.0", - "@stdlib/string-base-first-code-point": "^0.2.0", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.0", - "@stdlib/error-tools-fmtprodmsg": "^0.2.0", - "@stdlib/utils-regexp-from-string": "^0.2.0" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.0", - "@stdlib/assert-is-windows": "^0.2.0", - "@stdlib/process-exec-path": "^0.2.0", - "@stdlib/string-replace": "^0.2.0", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.0" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..0767914 --- /dev/null +++ b/stats.html @@ -0,0 +1,6177 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 8efd8909ebca24d4dcb9ca35f2f48730f3014057 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 15 Feb 2024 06:29:37 +0000 Subject: [PATCH 058/143] Update README.md for ESM bundle v0.2.0 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4f4d9a6..4e478ed 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.2.0-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -105,7 +105,7 @@ out = first( 'foo bar', 10 ); - - - - From ad00c69198996ac6ce6a6b313c8722a420c89972 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 25 Feb 2024 21:10:30 +0000 Subject: [PATCH 062/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ----- .github/workflows/publish.yml | 249 -- .github/workflows/publish_cli.yml | 176 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 132 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 228 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 4862 insertions(+), 5364 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index e898b7d..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..8d4680d --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.0-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3a97d0f..63e3912 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.1", - "@stdlib/assert-is-nonnegative-integer": "^0.2.1", - "@stdlib/assert-is-plain-object": "^0.2.1", - "@stdlib/assert-is-regexp-string": "^0.2.1", - "@stdlib/assert-is-string": "^0.2.1", - "@stdlib/cli-ctor": "^0.2.1", - "@stdlib/fs-read-file": "^0.2.1", - "@stdlib/process-read-stdin": "^0.2.1", - "@stdlib/regexp-eol": "^0.2.1", - "@stdlib/streams-node-stdin": "^0.2.1", - "@stdlib/string-base-first": "^0.2.1", - "@stdlib/string-base-first-code-point": "^0.2.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1", - "@stdlib/utils-regexp-from-string": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.1", - "@stdlib/assert-is-windows": "^0.2.1", - "@stdlib/process-exec-path": "^0.2.1", - "@stdlib/string-replace": "^0.2.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.1" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..925f760 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From afecc7c1de2091e76d541fbfce44c4b45778e431 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 25 Feb 2024 21:50:25 +0000 Subject: [PATCH 063/143] Update README.md for ESM bundle v0.2.1 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 95f5fae..a9fdcd6 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.2.1-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -105,7 +105,7 @@ out = first( 'foo bar', 10 ); - - - - From b0bf3a1d2e2d086f21f2c7d4b8324f35c48f1165 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 1 Mar 2024 13:59:40 +0000 Subject: [PATCH 067/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ----- .github/workflows/publish.yml | 249 -- .github/workflows/publish_cli.yml | 176 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 132 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 229 - .npmrc | 28 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4862 insertions(+), 5366 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 8de482d..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-03-01T05:59:17.608Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index e898b7d..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA corresponding to v2.0.0 - uses: act10ns/slack@ed1309ab9862e57e9e583e51c7889486b9a00b0f - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..401aebc --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3a97d0f..63e3912 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.1", - "@stdlib/assert-is-nonnegative-integer": "^0.2.1", - "@stdlib/assert-is-plain-object": "^0.2.1", - "@stdlib/assert-is-regexp-string": "^0.2.1", - "@stdlib/assert-is-string": "^0.2.1", - "@stdlib/cli-ctor": "^0.2.1", - "@stdlib/fs-read-file": "^0.2.1", - "@stdlib/process-read-stdin": "^0.2.1", - "@stdlib/regexp-eol": "^0.2.1", - "@stdlib/streams-node-stdin": "^0.2.1", - "@stdlib/string-base-first": "^0.2.1", - "@stdlib/string-base-first-code-point": "^0.2.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1", - "@stdlib/utils-regexp-from-string": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.1", - "@stdlib/assert-is-windows": "^0.2.1", - "@stdlib/process-exec-path": "^0.2.1", - "@stdlib/string-replace": "^0.2.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.1" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..3c21d95 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From a47f9ee99a5a256dde5126da075b8f938e94879d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Apr 2024 07:34:38 +0000 Subject: [PATCH 068/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8c830ea..3a97d0f 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.1", "@stdlib/string-base-first-code-point": "^0.2.1", "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/string-format": "^0.2.1", + "@stdlib/error-tools-fmtprodmsg": "^0.2.1", "@stdlib/utils-regexp-from-string": "^0.2.1", "@stdlib/error-tools-fmtprodmsg": "^0.2.1" }, From 3886fea3bbba68b186cf31514fdfc02ae46628b3 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Apr 2024 13:01:43 +0000 Subject: [PATCH 069/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 401aebc..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 3c21d95..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 0974459acc72d82bc6b77f2b21e6700067a40a14 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 1 Apr 2024 13:01:59 +0000 Subject: [PATCH 070/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ----- .github/workflows/publish.yml | 249 -- .github/workflows/publish_cli.yml | 176 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 132 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4862 insertions(+), 5369 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 416454e..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-04-01T05:15:35.195Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index df867aa..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..401aebc --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3a97d0f..63e3912 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.1", - "@stdlib/assert-is-nonnegative-integer": "^0.2.1", - "@stdlib/assert-is-plain-object": "^0.2.1", - "@stdlib/assert-is-regexp-string": "^0.2.1", - "@stdlib/assert-is-string": "^0.2.1", - "@stdlib/cli-ctor": "^0.2.1", - "@stdlib/fs-read-file": "^0.2.1", - "@stdlib/process-read-stdin": "^0.2.1", - "@stdlib/regexp-eol": "^0.2.1", - "@stdlib/streams-node-stdin": "^0.2.1", - "@stdlib/string-base-first": "^0.2.1", - "@stdlib/string-base-first-code-point": "^0.2.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1", - "@stdlib/utils-regexp-from-string": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.1", - "@stdlib/assert-is-windows": "^0.2.1", - "@stdlib/process-exec-path": "^0.2.1", - "@stdlib/string-replace": "^0.2.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.1" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..3c21d95 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 0f4926736726c5d40529c50469524b276c8cb9e1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 12 Apr 2024 03:49:24 +0000 Subject: [PATCH 071/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8c830ea..3a97d0f 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.1", "@stdlib/string-base-first-code-point": "^0.2.1", "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/string-format": "^0.2.1", + "@stdlib/error-tools-fmtprodmsg": "^0.2.1", "@stdlib/utils-regexp-from-string": "^0.2.1", "@stdlib/error-tools-fmtprodmsg": "^0.2.1" }, From 88959cc76ea3c04908951ffd022483878d4ff4fb Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 12 Apr 2024 09:14:13 +0000 Subject: [PATCH 072/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 401aebc..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 3c21d95..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From dfdb71ffbb53d48fc69ca13ae43273c4594d9c47 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 12 Apr 2024 09:14:35 +0000 Subject: [PATCH 073/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 49 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1012 ----- .github/workflows/publish.yml | 249 -- .github/workflows/publish_cli.yml | 176 - .github/workflows/test.yml | 100 - .github/workflows/test_bundles.yml | 189 - .github/workflows/test_coverage.yml | 134 - .github/workflows/test_install.yml | 86 - .gitignore | 188 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 129 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 4862 insertions(+), 5370 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 10a16e6..0000000 --- a/.gitattributes +++ /dev/null @@ -1,49 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/deps/** linguist-vendored=false -/lib/node_modules/** linguist-vendored=false linguist-generated=false -test/fixtures/** linguist-vendored=false -tools/** linguist-vendored=false - -# Override what is considered "documentation" by GitHub's linguist: -examples/** linguist-documentation=false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index df867aa..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1012 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - steps: ${{ toJson(steps) }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -265,7 +162,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -338,7 +235,7 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..401aebc --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3a97d0f..63e3912 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.1", - "@stdlib/assert-is-nonnegative-integer": "^0.2.1", - "@stdlib/assert-is-plain-object": "^0.2.1", - "@stdlib/assert-is-regexp-string": "^0.2.1", - "@stdlib/assert-is-string": "^0.2.1", - "@stdlib/cli-ctor": "^0.2.1", - "@stdlib/fs-read-file": "^0.2.1", - "@stdlib/process-read-stdin": "^0.2.1", - "@stdlib/regexp-eol": "^0.2.1", - "@stdlib/streams-node-stdin": "^0.2.1", - "@stdlib/string-base-first": "^0.2.1", - "@stdlib/string-base-first-code-point": "^0.2.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1", - "@stdlib/utils-regexp-from-string": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.1", - "@stdlib/assert-is-windows": "^0.2.1", - "@stdlib/process-exec-path": "^0.2.1", - "@stdlib/string-replace": "^0.2.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.1" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..3c21d95 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 9fa6959dcc5edc52adad25033b2a24667ef9a974 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 14 May 2024 16:28:06 +0000 Subject: [PATCH 074/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8c830ea..3a97d0f 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.1", "@stdlib/string-base-first-code-point": "^0.2.1", "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/string-format": "^0.2.1", + "@stdlib/error-tools-fmtprodmsg": "^0.2.1", "@stdlib/utils-regexp-from-string": "^0.2.1", "@stdlib/error-tools-fmtprodmsg": "^0.2.1" }, From a68c013bf8e74523c51ff98cc19056d481c238d5 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 14 May 2024 16:29:39 +0000 Subject: [PATCH 075/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 401aebc..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 3c21d95..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 921b7464e114f9b4b44abdf27c100dd909d1c05a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 14 May 2024 16:30:16 +0000 Subject: [PATCH 076/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ----- .github/workflows/publish.yml | 248 -- .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .gitignore | 188 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 5 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 4863 insertions(+), 5376 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 15fd596..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure git: - - name: 'Configure git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..401aebc --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 3a97d0f..63e3912 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.1", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.1", - "@stdlib/assert-is-nonnegative-integer": "^0.2.1", - "@stdlib/assert-is-plain-object": "^0.2.1", - "@stdlib/assert-is-regexp-string": "^0.2.1", - "@stdlib/assert-is-string": "^0.2.1", - "@stdlib/cli-ctor": "^0.2.1", - "@stdlib/fs-read-file": "^0.2.1", - "@stdlib/process-read-stdin": "^0.2.1", - "@stdlib/regexp-eol": "^0.2.1", - "@stdlib/streams-node-stdin": "^0.2.1", - "@stdlib/string-base-first": "^0.2.1", - "@stdlib/string-base-first-code-point": "^0.2.1", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1", - "@stdlib/utils-regexp-from-string": "^0.2.1", - "@stdlib/error-tools-fmtprodmsg": "^0.2.1" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.1", - "@stdlib/assert-is-windows": "^0.2.1", - "@stdlib/process-exec-path": "^0.2.1", - "@stdlib/string-replace": "^0.2.1", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.1" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..3c21d95 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 07c35353073cfdcc2be1774f69e10af6756240c6 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 29 Jul 2024 03:19:40 +0000 Subject: [PATCH 077/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 5d200e6..311c3bd 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From ede5d6cb7ba81a15dab99b08d4f40927ec658524 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 29 Jul 2024 03:44:54 +0000 Subject: [PATCH 078/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 401aebc..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.1-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.1-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.1-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.1-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.1-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.1-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.1-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.1-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 3c21d95..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 17b150b967d1e1f397a50952b542ea67be1d315d Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 29 Jul 2024 03:45:12 +0000 Subject: [PATCH 079/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ----- .github/workflows/publish.yml | 252 -- .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .gitignore | 190 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 195 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 48 files changed, 4863 insertions(+), 5572 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..1e373c0 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.1-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 311c3bd..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.1", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..4f8be49 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From ae005e7703d56c71e39524707f52d485258380d9 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 29 Jul 2024 03:51:55 +0000 Subject: [PATCH 080/143] Update README.md for ESM bundle v0.2.2 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ac6a994..b48ea70 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.2.2-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -105,7 +105,7 @@ out = first( 'foo bar', 10 ); - - - - From 5bdc3df3e9dfbbeec7e7467287675a77429b3fc1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Thu, 1 Aug 2024 13:20:01 +0000 Subject: [PATCH 084/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ----- .github/workflows/publish.yml | 252 -- .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .gitignore | 190 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 88 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5466 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 28860f4..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-08-01T06:09:11.407Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..d63709a --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 810e1dd101ba39e599412f7ad20df0afb63df4f0 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 1 Sep 2024 08:48:41 +0000 Subject: [PATCH 085/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 100c3ad74c71db6aa0bbba2df5cb78ca1cf385f5 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 1 Sep 2024 13:17:46 +0000 Subject: [PATCH 086/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index d63709a..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 5fbd6accbdd27c9097ed17633c8a022764492769 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 1 Sep 2024 13:18:01 +0000 Subject: [PATCH 087/143] Auto-generated commit --- .editorconfig | 181 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ----- .github/workflows/publish.yml | 252 -- .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .gitignore | 190 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 195 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 --- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 +++++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5573 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 60d743f..0000000 --- a/.editorconfig +++ /dev/null @@ -1,181 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 -insert_final_newline = false - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = false - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 861f791..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2024-09-01T06:37:15.951Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index c12f670..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..d63709a --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From d06174ba8c84a1b4ca3d73cb3a829ced565eafc8 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Mar 2025 00:29:30 +0000 Subject: [PATCH 088/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 6ad942c2ab58b4e174490bf1fe108b93e929c677 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Mar 2025 00:29:51 +0000 Subject: [PATCH 089/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index d63709a..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2024 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From d72fbe4736e247dbc151a4d2910079b0fe96f3cd Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 31 Mar 2025 00:30:11 +0000 Subject: [PATCH 090/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ---- .github/workflows/publish.yml | 252 - .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .github/workflows/test_published_package.yml | 105 - .gitignore | 194 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 195 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5681 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 472b9df..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2025-03-31T00:29:02.291Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..93f9815 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 332119e61ac4fd7d42edf340dacad9a585500f73 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 30 Jun 2025 00:50:33 +0000 Subject: [PATCH 091/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 8d3ecf13b1837cb5db3f907e2849d2356b4286d1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 30 Jun 2025 00:59:12 +0000 Subject: [PATCH 092/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 93f9815..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From a7a19b494e06e296b8e8a925a1261d4b2b782b53 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 30 Jun 2025 00:59:29 +0000 Subject: [PATCH 093/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ---- .github/workflows/publish.yml | 252 - .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .github/workflows/test_published_package.yml | 105 - .gitignore | 194 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 195 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5681 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 9146741..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2025-06-30T00:45:15.071Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 9590167..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H';\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..93f9815 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index dee5f3a..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H'; -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 1347fea09e55fd72052ff1bafbf40d0bb878a247 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 25 Aug 2025 03:02:40 +0000 Subject: [PATCH 094/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 2c77b98075ae52bbd9f46e670e72a70a60bc3961 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 25 Aug 2025 03:05:09 +0000 Subject: [PATCH 095/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 93f9815..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From aa71c317b8fea869b83c5d130de8e26606a6e0f1 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 25 Aug 2025 03:05:25 +0000 Subject: [PATCH 096/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ---- .github/workflows/publish.yml | 252 - .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .github/workflows/test_published_package.yml | 105 - .gitignore | 194 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 229 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5714 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..93f9815 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From d7be3c05e7c1a6f42e903810a34d89a714044759 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 6 Sep 2025 05:25:11 +0000 Subject: [PATCH 097/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 7fcb0fecde680ecf06eb242fa001d34b49b825c5 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 6 Sep 2025 05:29:33 +0000 Subject: [PATCH 098/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index dcb1eed..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 93f9815..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From cdef12578ecc57440fbb85a23c65b019b6a9edb8 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 6 Sep 2025 05:29:51 +0000 Subject: [PATCH 099/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1008 ---- .github/workflows/publish.yml | 252 - .github/workflows/publish_cli.yml | 175 - .github/workflows/test.yml | 99 - .github/workflows/test_bundles.yml | 186 - .github/workflows/test_coverage.yml | 133 - .github/workflows/test_install.yml | 85 - .github/workflows/test_published_package.yml | 105 - .gitignore | 194 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5715 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index 663474a..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1008 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send status to Slack channel if job fails: - - name: 'Send status to Slack channel in case of failure' - # Pin action to full length commit SHA - uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2 - with: - status: ${{ job.status }} - channel: '#npm-ci' - if: failure() - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..93f9815 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 8ef73998ab77d5ce702bd49103ee92d3e9c46e7f Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 31 Jan 2026 01:50:24 +0000 Subject: [PATCH 100/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 9d1e020..dfc7f28 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.2", "@stdlib/string-base-first-code-point": "^0.2.2", "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/string-format": "^0.2.2", + "@stdlib/error-tools-fmtprodmsg": "^0.2.2", "@stdlib/utils-regexp-from-string": "^0.2.2", "@stdlib/error-tools-fmtprodmsg": "^0.2.2" }, From 00601a741e2cfef8ad3a10b7f83fd76d8d50df4a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 31 Jan 2026 02:53:34 +0000 Subject: [PATCH 101/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index 93f9815..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2025 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 2c72e7fa13677074ece18e4b9777314821210327 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sat, 31 Jan 2026 02:53:55 +0000 Subject: [PATCH 102/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 108 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5838 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..ad00949 --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index dfc7f28..bc136cb 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.2", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.2", - "@stdlib/assert-is-nonnegative-integer": "^0.2.2", - "@stdlib/assert-is-plain-object": "^0.2.2", - "@stdlib/assert-is-regexp-string": "^0.2.2", - "@stdlib/assert-is-string": "^0.2.2", - "@stdlib/cli-ctor": "^0.2.2", - "@stdlib/fs-read-file": "^0.2.2", - "@stdlib/process-read-stdin": "^0.2.2", - "@stdlib/regexp-eol": "^0.2.2", - "@stdlib/streams-node-stdin": "^0.2.2", - "@stdlib/string-base-first": "^0.2.2", - "@stdlib/string-base-first-code-point": "^0.2.2", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2", - "@stdlib/utils-regexp-from-string": "^0.2.2", - "@stdlib/error-tools-fmtprodmsg": "^0.2.2" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.2", - "@stdlib/assert-is-windows": "^0.2.2", - "@stdlib/process-exec-path": "^0.2.2", - "@stdlib/string-replace": "^0.2.2", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.2" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..96538d6 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 56c1f8f25c8b5447311b21fd6b78e2cb4634a1a9 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 8 Feb 2026 18:13:12 +0000 Subject: [PATCH 103/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8208997..af02e1c 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From bffffbbc89263f6adf5bb66fea4e5e53d711ccbf Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 8 Feb 2026 19:10:38 +0000 Subject: [PATCH 104/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index ad00949..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.2-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.2-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.2-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.2-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.2-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.2-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.2-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.2-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 96538d6..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 9d11de9c76de195b1c7f3aae244d3a0aea8d47cc Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 8 Feb 2026 19:10:56 +0000 Subject: [PATCH 105/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5831 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..f5be24c --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.2-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index af02e1c..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.2", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..3bf52e1 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 3d9ea45ac5066c479911fd7303907d58b3d390cf Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 8 Feb 2026 19:34:28 +0000 Subject: [PATCH 106/143] Update README.md for ESM bundle v0.2.3 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e3b159f..5472856 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ limitations under the License. ## Usage ```javascript -import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@esm/index.mjs'; +import first from 'https://cdn.jsdelivr.net/gh/stdlib-js/string-first@v0.2.3-esm/index.mjs'; ``` #### first( str\[, n]\[, options] ) @@ -105,7 +105,7 @@ out = first( 'foo bar', 10 ); - - - - From a12b08315134c0b7c574de5f604df64dccb9507b Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 16 Feb 2026 04:15:17 +0000 Subject: [PATCH 110/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5832 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 8e732ec..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-02-16T02:16:10.363Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 54f4d0bba889e1db8f5b323f6643a073084a08ed Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Feb 2026 00:39:43 +0000 Subject: [PATCH 111/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 9038aba3e5dc0832e1e04954a070d6a7bccad2b0 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Feb 2026 00:40:13 +0000 Subject: [PATCH 112/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 8e15fed3ce1ad64ee90d525552404f1db07e177b Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Feb 2026 00:40:37 +0000 Subject: [PATCH 113/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5832 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 6569738..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-02-23T00:38:49.074Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 3e09612c33c46d01ccdc131e03df8c47a0845e9a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 2 Mar 2026 02:17:42 +0000 Subject: [PATCH 114/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 9c2bda5459a28934928ddd4b01a1f3e242005b9a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 2 Mar 2026 04:02:39 +0000 Subject: [PATCH 115/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 13f87ec0e927efe8c8dcd67db01c20201684f3fb Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 2 Mar 2026 04:02:56 +0000 Subject: [PATCH 116/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5832 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index e11276d..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-03-02T01:45:56.811Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 215cf2d0e628b2a38f0f9fd95910d7f586b40ee0 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 9 Mar 2026 02:49:08 +0000 Subject: [PATCH 117/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 87044717c157fdfd26bbe481146607185332dd77 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 9 Mar 2026 04:23:18 +0000 Subject: [PATCH 118/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 45f78f1f9cb651eb7f2b01ebbe8791e48cb9eaed Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 9 Mar 2026 04:23:38 +0000 Subject: [PATCH 119/143] Auto-generated commit --- .editorconfig | 180 - .eslintrc.js | 1 - .gitattributes | 66 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5832 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index dab5d2a..0000000 --- a/.editorconfig +++ /dev/null @@ -1,180 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 1c88e69..0000000 --- a/.gitattributes +++ /dev/null @@ -1,66 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index d29bd4a..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-03-09T02:13:01.547Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 8d514649f0a58ce055d25d72f2a04ac3f5dadc10 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Mar 2026 02:27:40 +0000 Subject: [PATCH 120/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 3b1d331691ca02391f012d42e79e0cc45359a5b2 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Mar 2026 04:03:04 +0000 Subject: [PATCH 121/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 53ec397fe1647c6c1a7e9ca9a30f6707eb6cfa48 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 23 Mar 2026 04:03:24 +0000 Subject: [PATCH 122/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5843 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 0990c50..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-03-23T01:57:29.038Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 9752f2fb3e9cdc81891c198dd6c8ac9b0fb58ebe Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 3 Apr 2026 03:27:38 +0000 Subject: [PATCH 123/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From c4ae0099e44169a0a62f1b22a5ab12630b8c6a03 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 3 Apr 2026 03:44:46 +0000 Subject: [PATCH 124/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From b1960922cf405b08272fafb35183fbadf8bfd892 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 3 Apr 2026 03:45:05 +0000 Subject: [PATCH 125/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 230 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 145 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5843 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index bb43925..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-04-03T03:23:42.512Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 8be22b8..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,145 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=grapheme', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_point', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( pkg+':mode=code_unit', function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 4cdb456e76ff5ce1e1e2f33284d83673d24fb31b Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 19 Apr 2026 07:32:32 +0000 Subject: [PATCH 126/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 34051e290d5ce1f0c5944284666c8784a20abaf8 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 19 Apr 2026 07:44:29 +0000 Subject: [PATCH 127/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 262809fc0dc6858eac9ee02c5078bc76227fb7e4 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 19 Apr 2026 07:44:49 +0000 Subject: [PATCH 128/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 199 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 265 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5878 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From c4f0085eb570eb03439b7a6a8586d81b0b08904c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 10 May 2026 03:48:04 +0000 Subject: [PATCH 129/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From b4808ab0594649b686d358a2d5c17cd27655fa6a Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 10 May 2026 04:04:07 +0000 Subject: [PATCH 130/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 823ccfb64ec16da3ad5d24bca2240a6b505f66db Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 10 May 2026 04:04:23 +0000 Subject: [PATCH 131/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 204 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 265 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5884 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 6d3b395..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-05-10T03:37:03.511Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 472c66aaae1f22fbf7902cdc3a207ad143d8303c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 11 May 2026 03:22:33 +0000 Subject: [PATCH 132/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 16c6512f869b3f2619690f189bbd530befbc2088 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 11 May 2026 03:57:43 +0000 Subject: [PATCH 133/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 91de5cd2e0da0bd28a4bd2df7dc56a788c75a563 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Mon, 11 May 2026 03:58:00 +0000 Subject: [PATCH 134/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 204 - .npmignore | 229 - .npmrc | 31 - CHANGELOG.md | 265 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5884 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 8020fb0..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-05-11T03:21:03.396Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From d74d6cbce9e60e6cc4069d76534ec10b60d97838 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 31 May 2026 09:16:40 +0000 Subject: [PATCH 135/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From d0fa363be4c48eb30fdcd4377485ca783156a745 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 31 May 2026 09:21:57 +0000 Subject: [PATCH 136/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 6484c3a..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns updated string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns updated string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From 15a873da7b13465d3379ad5e9da5001d597d88cd Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Sun, 31 May 2026 09:22:13 +0000 Subject: [PATCH 137/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 204 - .npmignore | 229 - .npmrc | 44 - CHANGELOG.md | 268 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 49 files changed, 4863 insertions(+), 5899 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 01b3db7..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){return e||i((e={exports:{}}).exports,e),e.exports}};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),n=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,a,t,r;if(!d(i))throw new TypeError(n('1gp3F',i));if(t={mode:"grapheme"},a=arguments.length,a===1)r=1;else if(a===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(n('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(n('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(n('1gp2V',e))}if(e&&f(e,"mode")&&(t.mode=e.mode,!q(t.mode)))throw new TypeError(n('1gpE1',"mode",u.join('", "'),t.mode));return w[t.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 21bed46..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "uGAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From 0f7b1481adcbd09d8e84c33c0e0944b885ff6d97 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 19 Jun 2026 03:34:50 +0000 Subject: [PATCH 138/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 1408f8fd08c13f6f09fae89fc45c8be3f97813ef Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 19 Jun 2026 03:52:06 +0000 Subject: [PATCH 139/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 8852086..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns output string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns output string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From fc4d36584ce9e111d021e7faadc615e8e7b0adef Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Fri, 19 Jun 2026 03:52:24 +0000 Subject: [PATCH 140/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 204 - .npmignore | 229 - .npmrc | 44 - CHANGELOG.md | 268 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5900 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index c482c9b..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-06-19T03:31:19.047Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 7d05bad..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){try{return e||i((e={exports:{}}).exports,e),e.exports}catch(t){throw (e=0, t)}};};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),a=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,t,n,r;if(!d(i))throw new TypeError(a('1gp3F',i));if(n={mode:"grapheme"},t=arguments.length,t===1)r=1;else if(t===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(a('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(a('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(a('1gp2V',e))}if(e&&f(e,"mode")&&(n.mode=e.mode,!q(n.mode)))throw new TypeError(a('1gpE1',"mode",u.join('", "'),n.mode));return w[n.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 752fa2b..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "iIAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -}); From daa8f23aec0a7936c4a4a65243eb38fe21d71e7c Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 23 Jun 2026 03:45:53 +0000 Subject: [PATCH 141/143] Transform error messages --- lib/main.js | 12 ++++++------ package.json | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/main.js b/lib/main.js index 5971a1a..27fe5b8 100644 --- a/lib/main.js +++ b/lib/main.js @@ -28,7 +28,7 @@ var contains = require( '@stdlib/array-base-assert-contains' ).factory; var firstCodeUnit = require( '@stdlib/string-base-first' ); var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/string-format' ); +var format = require( '@stdlib/error-tools-fmtprodmsg' ); // VARIABLES // @@ -88,7 +88,7 @@ function first( str ) { var n; if ( !isString( str ) ) { - throw new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) ); + throw new TypeError( format( '1gp3F', str ) ); } opts = { 'mode': 'grapheme' @@ -102,23 +102,23 @@ function first( str ) { options = n; n = 1; } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } } else { // nargs > 2 n = arguments[ 1 ]; if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) ); + throw new TypeError( format( '1gp3X', n ) ); } options = arguments[ 2 ]; if ( !isPlainObject( options ) ) { - throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) ); + throw new TypeError( format( '1gp2V', options ) ); } } if ( options ) { if ( hasOwnProp( options, 'mode' ) ) { opts.mode = options.mode; if ( !isMode( opts.mode ) ) { - throw new TypeError( format( 'invalid option. `%s` option must be one of the following: "%s". Value: `%s`.', 'mode', MODES.join( '", "' ), opts.mode ) ); + throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); } } } diff --git a/package.json b/package.json index 8d54291..5868346 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "@stdlib/string-base-first": "^0.2.3", "@stdlib/string-base-first-code-point": "^0.2.3", "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/string-format": "^0.2.3", + "@stdlib/error-tools-fmtprodmsg": "^0.2.3", "@stdlib/utils-regexp-from-string": "^0.2.3", "@stdlib/error-tools-fmtprodmsg": "^0.2.3" }, From 6766b2f977032867f5518f4d1e45bb7aea64b140 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 23 Jun 2026 04:03:00 +0000 Subject: [PATCH 142/143] Remove files --- index.d.ts | 118 -- index.mjs | 4 - index.mjs.map | 1 - stats.html | 4842 ------------------------------------------------- 4 files changed, 4965 deletions(-) delete mode 100644 index.d.ts delete mode 100644 index.mjs delete mode 100644 index.mjs.map delete mode 100644 stats.html diff --git a/index.d.ts b/index.d.ts deleted file mode 100644 index 8852086..0000000 --- a/index.d.ts +++ /dev/null @@ -1,118 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -// TypeScript Version: 4.1 - -/* eslint-disable @typescript-eslint/unified-signatures */ - -/** -* Interface describing function options. -*/ -interface Options { - /** - * Specifies the type of characters to return (default: 'grapheme'). - * - * ## Notes - * - * - The following option values are supported: - * - * - `'grapheme'`: grapheme clusters. Appropriate for strings containing visual characters which can span multiple Unicode code points (e.g., emoji). - * - `'code_point'`: Unicode code points. Appropriate for strings containing visual characters which are comprised of more than one Unicode code unit (e.g., ideographic symbols and punctuation and mathematical alphanumerics). - * - `'code_unit'`: UTF-16 code units. Appropriate for strings containing visual characters drawn from the basic multilingual plane (BMP) (e.g., common characters, such as those from the Latin, Greek, and Cyrillic alphabets). - */ - mode?: 'grapheme' | 'code_point' | 'code_unit'; -} - -/** -* Returns the first `n` characters of a string. -* -* @param str - input string -* @param n - number of characters to return -* @param options - options -* @returns output string -* -* @example -* var out = first( 'last man standing', 2 ); -* // returns 'la' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2, { -* 'mode': 'grapheme' -* }); -* // returns '🐶🐮' -*/ -declare function first( str: string, n: number, options?: Options ): string; - -/** -* Returns the first character of a string. -* -* @param str - input string -* @param options - options -* @returns output string -* -* @example -* var out = first( 'last man standing', { -* 'mode': 'code_unit' -* }); -* // returns 'l' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', { -* 'mode': 'grapheme' -* }); -* // returns '🐶' -*/ -declare function first( str: string, options?: Options ): string; - -/** -* Returns the first character(s) of a string. -* -* @param str - input string -* @param n - number of characters to return (default: 1) -* @returns output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -declare function first( str: string, n?: number ): string; - - -// EXPORTS // - -export = first; diff --git a/index.mjs b/index.mjs deleted file mode 100644 index afaf1ca..0000000 --- a/index.mjs +++ /dev/null @@ -1,4 +0,0 @@ -// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 -/// -import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; -//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map deleted file mode 100644 index 4d2dc9f..0000000 --- a/index.mjs.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/stats.html b/stats.html deleted file mode 100644 index 7cca235..0000000 --- a/stats.html +++ /dev/null @@ -1,4842 +0,0 @@ - - - - - - - - Rollup Visualizer - - - -
- - - - - From ce6154036cf85fd5cde48116165b7d56158c46d3 Mon Sep 17 00:00:00 2001 From: stdlib-bot Date: Tue, 23 Jun 2026 04:03:20 +0000 Subject: [PATCH 143/143] Auto-generated commit --- .editorconfig | 189 - .eslintrc.js | 1 - .gitattributes | 68 - .github/.keepalive | 1 - .github/PULL_REQUEST_TEMPLATE.md | 7 - .github/workflows/benchmark.yml | 64 - .github/workflows/cancel.yml | 57 - .github/workflows/close_pull_requests.yml | 54 - .github/workflows/examples.yml | 64 - .github/workflows/npm_downloads.yml | 112 - .github/workflows/productionize.yml | 1044 ---- .github/workflows/publish.yml | 261 - .github/workflows/publish_cli.yml | 184 - .github/workflows/test.yml | 101 - .github/workflows/test_bundles.yml | 213 - .github/workflows/test_coverage.yml | 142 - .github/workflows/test_install.yml | 94 - .github/workflows/test_published_package.yml | 115 - .gitignore | 204 - .npmignore | 229 - .npmrc | 44 - CHANGELOG.md | 268 - CITATION.cff | 30 - CODE_OF_CONDUCT.md | 3 - CONTRIBUTING.md | 3 - Makefile | 534 -- README.md | 131 +- SECURITY.md | 5 - benchmark/benchmark.js | 146 - bin/cli | 130 - branches.md | 60 - dist/index.d.ts | 3 - dist/index.js | 5 - dist/index.js.map | 7 - docs/repl.txt | 48 - docs/types/test.ts | 111 - docs/usage.txt | 10 - etc/cli_opts.json | 19 - examples/index.js | 42 - docs/types/index.d.ts => index.d.ts | 0 index.mjs | 4 + index.mjs.map | 1 + lib/index.js | 46 - lib/main.js | 131 - package.json | 75 +- stats.html | 4842 ++++++++++++++++++ test/dist/test.js | 33 - test/fixtures/stdin_error.js.txt | 33 - test/test.cli.js | 389 -- test/test.js | 406 -- 50 files changed, 4863 insertions(+), 5900 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .eslintrc.js delete mode 100644 .gitattributes delete mode 100644 .github/.keepalive delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/benchmark.yml delete mode 100644 .github/workflows/cancel.yml delete mode 100644 .github/workflows/close_pull_requests.yml delete mode 100644 .github/workflows/examples.yml delete mode 100644 .github/workflows/npm_downloads.yml delete mode 100644 .github/workflows/productionize.yml delete mode 100644 .github/workflows/publish.yml delete mode 100644 .github/workflows/publish_cli.yml delete mode 100644 .github/workflows/test.yml delete mode 100644 .github/workflows/test_bundles.yml delete mode 100644 .github/workflows/test_coverage.yml delete mode 100644 .github/workflows/test_install.yml delete mode 100644 .github/workflows/test_published_package.yml delete mode 100644 .gitignore delete mode 100644 .npmignore delete mode 100644 .npmrc delete mode 100644 CHANGELOG.md delete mode 100644 CITATION.cff delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 SECURITY.md delete mode 100644 benchmark/benchmark.js delete mode 100755 bin/cli delete mode 100644 branches.md delete mode 100644 dist/index.d.ts delete mode 100644 dist/index.js delete mode 100644 dist/index.js.map delete mode 100644 docs/repl.txt delete mode 100644 docs/types/test.ts delete mode 100644 docs/usage.txt delete mode 100644 etc/cli_opts.json delete mode 100644 examples/index.js rename docs/types/index.d.ts => index.d.ts (100%) create mode 100644 index.mjs create mode 100644 index.mjs.map delete mode 100644 lib/index.js delete mode 100644 lib/main.js create mode 100644 stats.html delete mode 100644 test/dist/test.js delete mode 100644 test/fixtures/stdin_error.js.txt delete mode 100644 test/test.cli.js delete mode 100644 test/test.js diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 80f3fca..0000000 --- a/.editorconfig +++ /dev/null @@ -1,189 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# EditorConfig configuration file (see ). - -# Indicate that this file is a root-level configuration file: -root = true - -# Set properties for all files: -[*] -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true - -# Set properties for JavaScript files: -[*.{js,js.txt}] -indent_style = tab - -# Set properties for JavaScript ES module files: -[*.{mjs,mjs.txt}] -indent_style = tab - -# Set properties for JavaScript CommonJS files: -[*.{cjs,cjs.txt}] -indent_style = tab - -# Set properties for JSON files: -[*.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `cli_opts.json` files: -[cli_opts.json] -indent_style = tab - -# Set properties for TypeScript files: -[*.ts] -indent_style = tab - -# Set properties for Python files: -[*.{py,py.txt}] -indent_style = space -indent_size = 4 - -# Set properties for Julia files: -[*.{jl,jl.txt}] -indent_style = tab - -# Set properties for R files: -[*.{R,R.txt}] -indent_style = tab - -# Set properties for C files: -[*.{c,c.txt}] -indent_style = tab - -# Set properties for C header files: -[*.{h,h.txt}] -indent_style = tab - -# Set properties for C++ files: -[*.{cpp,cpp.txt}] -indent_style = tab - -# Set properties for C++ header files: -[*.{hpp,hpp.txt}] -indent_style = tab - -# Set properties for Fortran files: -[*.{f,f.txt}] -indent_style = space -indent_size = 2 - -# Set properties for shell files: -[*.{sh,sh.txt}] -indent_style = tab - -# Set properties for AWK files: -[*.{awk,awk.txt}] -indent_style = tab - -# Set properties for HTML files: -[*.{html,html.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for XML files: -[*.{xml,xml.txt}] -indent_style = tab -tab_width = 2 - -# Set properties for CSS files: -[*.{css,css.txt}] -indent_style = tab - -# Set properties for Makefiles: -[Makefile] -indent_style = tab - -[*.{mk,mk.txt}] -indent_style = tab - -# Set properties for Markdown files: -[*.{md,md.txt}] -indent_style = space -indent_size = 4 -trim_trailing_whitespace = true # Note: this disables using two spaces to force a hard line break, which is permitted in Markdown. As we don't typically follow that practice (TMK), we should be safe to automatically trim. - -# Set properties for `usage.txt` files: -[usage.txt] -indent_style = space -indent_size = 2 - -# Set properties for `repl.txt` files: -[repl.txt] -indent_style = space -indent_size = 4 - -# Set properties for `package.json` files: -[package.{json,json.txt}] -indent_style = space -indent_size = 2 - -# Set properties for `datapackage.json` files: -[datapackage.json] -indent_style = space -indent_size = 2 - -# Set properties for `manifest.json` files: -[manifest.json] -indent_style = space -indent_size = 2 - -# Set properties for `tsconfig.json` files: -[tsconfig.json] -indent_style = space -indent_size = 2 - -# Set properties for LaTeX files: -[*.{tex,tex.txt}] -indent_style = tab - -# Set properties for LaTeX Bibliography files: -[*.{bib,bib.txt}] -indent_style = tab - -# Set properties for YAML files: -[*.{yml,yml.txt}] -indent_style = space -indent_size = 2 - -# Ignore generated lock files for GitHub Agentic Workflows: -[*.lock.yml] -charset = unset -end_of_line = unset -indent_style = unset -indent_size = unset -trim_trailing_whitespace = unset -insert_final_newline = unset - -# Set properties for GYP files: -[binding.gyp] -indent_style = space -indent_size = 2 - -[*.gypi] -indent_style = space -indent_size = 2 - -# Set properties for citation files: -[*.{cff,cff.txt}] -indent_style = space -indent_size = 2 diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index 5f30286..0000000 --- a/.eslintrc.js +++ /dev/null @@ -1 +0,0 @@ -/* For the `eslint` rules of this project, consult the main repository at https://github.com/stdlib-js/stdlib */ diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 24b327f..0000000 --- a/.gitattributes +++ /dev/null @@ -1,68 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2017 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Configuration file which assigns attributes to pathnames. -# -# [1]: https://git-scm.com/docs/gitattributes - -# Automatically normalize the line endings of any committed text files: -* text=auto - -# Override line endings for certain files on checkout: -*.crlf.csv text eol=crlf - -# Denote that certain files are binary and should not be modified: -*.png binary -*.jpg binary -*.jpeg binary -*.gif binary -*.ico binary -*.gz binary -*.zip binary -*.7z binary -*.mp3 binary -*.mp4 binary -*.mov binary - -# Override what is considered "vendored" by GitHub's linguist: -/lib/node_modules/** -linguist-vendored -linguist-generated - -# Configure directories which should *not* be included in GitHub language statistics: -/deps/** linguist-vendored -/dist/** linguist-generated -/workshops/** linguist-vendored - -benchmark/** linguist-vendored -docs/* linguist-documentation -etc/** linguist-vendored -examples/** linguist-documentation -scripts/** linguist-vendored -test/** linguist-vendored -tools/** linguist-vendored - -# Configure files which should *not* be included in GitHub language statistics: -Makefile linguist-vendored -*.mk linguist-vendored -*.jl linguist-vendored -*.py linguist-vendored -*.R linguist-vendored - -# Configure files which should be included in GitHub language statistics: -docs/types/*.d.ts -linguist-documentation - -.github/workflows/*.lock.yml linguist-generated=true merge=ours diff --git a/.github/.keepalive b/.github/.keepalive deleted file mode 100644 index 8654bc4..0000000 --- a/.github/.keepalive +++ /dev/null @@ -1 +0,0 @@ -2026-06-23T03:34:03.648Z diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index f6150db..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,7 +0,0 @@ - - -We are excited about your pull request, but unfortunately we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. - -If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. You may also consult the [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/contributing/development.md) for help on developing stdlib. - -We look forward to receiving your contribution! :smiley: \ No newline at end of file diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml deleted file mode 100644 index e4f10fe..0000000 --- a/.github/workflows/benchmark.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: benchmark - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run benchmarks: - benchmark: - - # Define a display name: - name: 'Run benchmarks' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run benchmarks: - - name: 'Run benchmarks' - run: | - npm run benchmark diff --git a/.github/workflows/cancel.yml b/.github/workflows/cancel.yml deleted file mode 100644 index b5291db..0000000 --- a/.github/workflows/cancel.yml +++ /dev/null @@ -1,57 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: cancel - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to cancel existing workflow runs: - cancel: - - # Define a display name: - name: 'Cancel workflow runs' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Time limit: - timeout-minutes: 3 - - # Define the sequence of job steps... - steps: - - # Cancel existing workflow runs: - - name: 'Cancel existing workflow runs' - # Pin action to full length commit SHA - uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # v0.12.1 - with: - workflow_id: >- - benchmark.yml, - examples.yml, - test.yml, - test_coverage.yml, - test_install.yml, - publish.yml - access_token: ${{ github.token }} diff --git a/.github/workflows/close_pull_requests.yml b/.github/workflows/close_pull_requests.yml deleted file mode 100644 index f3c36a7..0000000 --- a/.github/workflows/close_pull_requests.yml +++ /dev/null @@ -1,54 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: close_pull_requests - -# Workflow triggers: -on: - pull_request_target: - types: [opened] - -# Workflow jobs: -jobs: - - # Define job to close all pull requests: - run: - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Close pull request - - name: 'Close pull request' - # Pin action to full length commit SHA corresponding to v3.1.2 - uses: superbrothers/close-pull-request@9c18513d320d7b2c7185fb93396d0c664d5d8448 - with: - comment: | - Thank you for submitting a pull request. :raised_hands: - - We greatly appreciate your willingness to submit a contribution. However, we are not accepting pull requests against this repository, as all development happens on the [main project repository](https://github.com/stdlib-js/stdlib). - - We kindly request that you submit this pull request against the [respective directory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first) of the main repository where we’ll review and provide feedback. If this is your first stdlib contribution, be sure to read the [contributing guide](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) which provides guidelines and instructions for submitting contributions. - - Thank you again, and we look forward to receiving your contribution! :smiley: - - Best, - The stdlib team \ No newline at end of file diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml deleted file mode 100644 index 2984901..0000000 --- a/.github/workflows/examples.yml +++ /dev/null @@ -1,64 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2021 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: examples - -# Workflow triggers: -on: - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job to run the package examples... - examples: - - # Define display name: - name: 'Run examples' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - - # Checkout repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Run examples: - - name: 'Run examples' - run: | - npm run examples diff --git a/.github/workflows/npm_downloads.yml b/.github/workflows/npm_downloads.yml deleted file mode 100644 index 2de7dc6..0000000 --- a/.github/workflows/npm_downloads.yml +++ /dev/null @@ -1,112 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: npm_downloads - -# Workflow triggers: -on: - # Run this workflow weekly: - schedule: - # cron: ' ' - - cron: '3 3 * * 6' - - # Allow the workflow to be manually run: - workflow_dispatch: - -# Workflow jobs: -jobs: - - # Define a job for retrieving npm download counts... - npm_downloads: - - # Define display name: - name: 'Retrieve npm download counts' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - timeout-minutes: 10 - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Resolve package name: - - name: 'Resolve package name' - id: package_name - run: | - name=`node -e 'console.log(require("./package.json").name)' | tr -d '\n'` - echo "package_name=$name" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Fetch download data: - - name: 'Fetch data' - id: download_data - run: | - url="https://api.npmjs.org/downloads/range/$(date --date='1 year ago' '+%Y-%m-%d'):$(date '+%Y-%m-%d')/${{ steps.package_name.outputs.package_name }}" - echo "$url" - data=$(curl "$url") - mkdir ./tmp - echo "$data" > ./tmp/npm_downloads.json - echo "data=$data" >> $GITHUB_OUTPUT - timeout-minutes: 5 - - # Print summary of download data: - - name: 'Print summary' - run: | - echo "| Date | Downloads |" >> $GITHUB_STEP_SUMMARY - echo "|------|------------|" >> $GITHUB_STEP_SUMMARY - cat ./tmp/npm_downloads.json | jq -r ".downloads | .[-14:] | to_entries | map(\"| \(.value.day) | \(.value.downloads) |\") |.[]" >> $GITHUB_STEP_SUMMARY - - # Upload the download data: - - name: 'Upload data' - # Pin action to full length commit SHA - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 - with: - # Define a name for the uploaded artifact (ensuring a unique name for each job): - name: npm_downloads - - # Specify the path to the file to upload: - path: ./tmp/npm_downloads.json - - # Specify the number of days to retain the artifact (default is 90 days): - retention-days: 90 - timeout-minutes: 10 - if: success() - - # Send data to events server: - - name: 'Post data' - # Pin action to full length commit SHA - uses: distributhor/workflow-webhook@48a40b380ce4593b6a6676528cd005986ae56629 # v3.0.3 - env: - webhook_url: ${{ secrets.STDLIB_NPM_DOWNLOADS_URL }} - webhook_secret: ${{ secrets.STDLIB_WEBHOOK_SECRET }} - data: '{ "downloads": ${{ steps.download_data.outputs.data }} }' - timeout-minutes: 5 - if: success() diff --git a/.github/workflows/productionize.yml b/.github/workflows/productionize.yml deleted file mode 100644 index a74ef1e..0000000 --- a/.github/workflows/productionize.yml +++ /dev/null @@ -1,1044 +0,0 @@ -#/ -# @license Apache-2.0 -# -# Copyright (c) 2022 The Stdlib Authors. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -#/ - -# Workflow name: -name: productionize - -# Workflow triggers: -on: - # Run workflow when a new commit is pushed to the main branch: - push: - branches: - - main - - # Allow the workflow to be manually run: - workflow_dispatch: - inputs: - require-passing-tests: - description: 'Require passing tests for creating bundles' - type: boolean - default: true - - # Run workflow upon completion of `publish` workflow run: - workflow_run: - workflows: ["publish"] - types: [completed] - -# Concurrency group to prevent multiple concurrent executions: -concurrency: - group: productionize - cancel-in-progress: true - -# Workflow jobs: -jobs: - - # Define a job to create a production build... - productionize: - - # Define display name: - name: 'Productionize' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Define the sequence of job steps... - steps: - # Checkout main branch of repository: - - name: 'Checkout main branch' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - ref: main - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Create production branch: - - name: 'Create production branch' - run: | - git checkout -b production - - # Transform error messages: - - name: 'Transform error messages' - id: transform-error-messages - uses: stdlib-js/transform-errors-action@main - - # Change `@stdlib/string-format` to `@stdlib/error-tools-fmtprodmsg` in package.json if the former is a dependency, otherwise insert it as a dependency: - - name: 'Update dependencies in package.json' - run: | - PKG_VERSION=$(npm view @stdlib/error-tools-fmtprodmsg version) - if grep -q '"@stdlib/string-format"' package.json; then - sed -i "s/\"@stdlib\/string-format\": \"^.*\"/\"@stdlib\/error-tools-fmtprodmsg\": \"^$PKG_VERSION\"/g" package.json - else - node -e "var pkg = require( './package.json' ); pkg.dependencies[ '@stdlib/error-tools-fmtprodmsg' ] = '^$PKG_VERSION'; require( 'fs' ).writeFileSync( 'package.json', JSON.stringify( pkg, null, 2 ) );" - fi - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Transform error messages" - - # Push changes: - - name: 'Push changes' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" production --force - - # Define a job for running tests of the productionized code... - test: - - # Define a display name: - name: 'Run Tests' - - # Define the type of virtual host machine: - runs-on: 'ubuntu-latest' - - # Indicate that this job depends on the prior job finishing: - needs: productionize - - # Run this job regardless of the outcome of the prior job: - if: always() - - # Define the sequence of job steps... - steps: - - # Checkout the repository: - - name: 'Checkout repository' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - with: - # Use the `production` branch: - ref: production - - # Install Node.js: - - name: 'Install Node.js' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Build native add-on if present: - - name: 'Build native add-on (if present)' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - run: | - if [ -f "binding.gyp" ]; then - npm install node-gyp --no-save && ./node_modules/.bin/node-gyp rebuild - fi - - # Run tests: - - name: 'Run tests' - if: ${{ github.event.inputs.require-passing-tests == 'true' }} - id: tests - run: | - npm test || npm test || npm test - - # Define job to create a bundle for use in Deno... - deno: - - # Define display name: - name: 'Create Deno bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `deno` branch exists: - - name: 'Check if remote `deno` branch exists' - id: deno-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin deno - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `deno` exists, delete everything in branch and merge `production` into it - - name: 'If `deno` exists, delete everything in branch and merge `production` into it' - if: steps.deno-branch-exists.outputs.remote-exists - run: | - git checkout -b deno origin/deno - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `deno` does not exist, create `deno` branch: - - name: 'If `deno` does not exist, create `deno` branch' - if: ${{ steps.deno-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b deno - - # Copy files to deno directory: - - name: 'Copy files to deno directory' - run: | - mkdir -p deno - cp README.md LICENSE CONTRIBUTORS NOTICE ./deno - - # Copy TypeScript definitions to deno directory: - if [ -d index.d.ts ]; then - cp index.d.ts ./deno/index.d.ts - fi - if [ -e ./docs/types/index.d.ts ]; then - cp ./docs/types/index.d.ts ./deno/mod.d.ts - fi - - # Install Node.js: - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: Install production and development dependencies - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Bundle package for use in Deno: - - name: 'Bundle package for Deno' - id: deno-bundle - uses: stdlib-js/bundle-action@main - with: - target: 'deno' - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the deno branch: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/deno/"; - - # Replace reference to `@stdlib/types` with CDN link: - find ./deno -type f -name '*.ts' -print0 | xargs -0 sed -Ei "s/\/\/\/ /\/\/\/ /g" - - # Change wording of project description to avoid reference to JavaScript and Node.js: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "s/a standard library for JavaScript and Node.js, /a standard library /g" - - # Rewrite all `require()`s to use jsDelivr links: - find ./deno -type f -name '*.md' -print0 | xargs -0 sed -Ei "/require\( '@stdlib\// { - s/(var|let|const)\s+([a-z0-9_]+)\s+=\s*require\( '([^']+)' \);/import \2 from \'\3\';/i - s/@stdlib/https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js/ - s/';/@deno\/mod.js';/ - }" - - # Rewrite first `import` to show importing of named exports if available: - exports=$(cat lib/index.js | \ - grep -E 'setReadOnly\(.*,.*,.*\)' | \ - sed -E 's/setReadOnly\((.*),(.*),(.*)\);/\2/' | \ - sed -E "s/'//g" | \ - sort) - if [ -n "$exports" ]; then - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\nimport\s+([a-zA-Z0-9_]+)\s+from\s*'([^']+)';\n\`\`\`/\`\`\`javascript\nimport \1 from '\2';\n\`\`\`\n\nYou can also import the following named exports from the package:\n\n\`\`\`javascript\nimport { $(echo $exports | sed -E 's/ /, /g') } from '\2';\n\`\`\`/" - fi - - # Remove `installation`, `cli`, and `c` sections: - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./deno -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Create package.json file for deno branch: - jq --indent 2 '{"name": .name, "version": .version, "description": .description, "license": .license, "type": "module", "main": "./mod.js", "homepage": .homepage, "repository": .repository, "bugs": .bugs, "keywords": .keywords, "funding": .funding}' package.json > ./deno/package.json - - # Delete everything in current directory aside from deno folder: - - name: 'Delete everything in current directory aside from deno folder' - run: | - find . -type 'f' | grep -v -e "deno" -e ".git/" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e "deno" -e ".git" | xargs -r rm -rf - - # Move deno directory to root: - - name: 'Move deno directory to root' - run: | - mv ./deno/* . - rmdir ./deno - - # Commit changes: - - name: 'Commit changes' - run: | - git add -A - git commit -m "Auto-generated commit" - - # Push changes to `deno` branch: - - name: 'Push changes to `deno` branch' - run: | - SLUG=${{ github.repository }} - echo "Pushing changes to $SLUG..." - git push "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$SLUG.git" deno - - # Send notification to Zulip if job fails: - - name: 'Send notification to Zulip in case of failure' - # Pin action to full length commit SHA - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1.0.2 - if: failure() - with: - api-key: ${{ secrets.ZULIP_API_KEY }} - email: 'github-actions-bot@stdlib.zulipchat.com' - organization-url: 'https://stdlib.zulipchat.com' - to: 'workflows-standalone' - type: 'stream' - topic: ${{ github.event.repository.name }} - content: | - :cross_mark: **${{ github.workflow }}** workflow failed - - **Repository:** [${{ github.repository }}](${{ github.server_url }}/${{ github.repository }}) - **Run:** [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) - - # Define job to create a UMD bundle... - umd: - - # Define display name: - name: 'Create UMD bundle' - - # Define the type of virtual host machine on which to run the job: - runs-on: ubuntu-latest - - # Indicate that this job depends on the test job finishing: - needs: test - - # Define the sequence of job steps... - steps: - # Checkout the repository: - - name: 'Checkout repository' - # Pin action to full length commit SHA - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0 - - # Configure Git: - - name: 'Configure Git' - run: | - git config --local user.email "noreply@stdlib.io" - git config --local user.name "stdlib-bot" - - # Check if remote `umd` branch exists: - - name: 'Check if remote `umd` branch exists' - id: umd-branch-exists - continue-on-error: true - run: | - git fetch --all - git ls-remote --exit-code --heads origin umd - if [ $? -eq 0 ]; then - echo "remote-exists=true" >> $GITHUB_OUTPUT - else - echo "remote-exists=false" >> $GITHUB_OUTPUT - fi - - # If `umd` exists, delete everything in branch and merge `production` into it - - name: 'If `umd` exists, delete everything in branch and merge `production` into it' - if: steps.umd-branch-exists.outputs.remote-exists - run: | - git checkout -b umd origin/umd - - find . -type 'f' | grep -v -e ".git/" -e "package.json" -e "README.md" -e "LICENSE" -e "CONTRIBUTORS" -e "NOTICE" | xargs -r rm - find . -mindepth 1 -type 'd' | grep -v -e ".git" | xargs -r rm -rf - - git add -A - git commit -m "Remove files" --allow-empty - - git config merge.theirs.name 'simulate `-s theirs`' - git config merge.theirs.driver 'cat %B > %A' - GIT_CONFIG_PARAMETERS="'merge.default=theirs'" git merge origin/production --allow-unrelated-histories - - # Copy files from `production` branch if necessary: - git checkout origin/production -- . - if [ -n "$(git status --porcelain)" ]; then - git add -A - git commit -m "Auto-generated commit" - fi - - # If `umd` does not exist, create `umd` branch: - - name: 'If `umd` does not exist, create `umd` branch' - if: ${{ steps.umd-branch-exists.outputs.remote-exists == false }} - run: | - git checkout production - git checkout -b umd - - # Copy files to umd directory: - - name: 'Copy files to umd directory' - run: | - mkdir -p umd - cp README.md LICENSE CONTRIBUTORS NOTICE ./umd - - # Install Node.js - - name: 'Install Node.js' - # Pin action to full length commit SHA - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1 - with: - node-version: 20 - timeout-minutes: 5 - - # Install dependencies: - - name: 'Install production and development dependencies' - id: install - run: | - npm install || npm install || npm install - timeout-minutes: 15 - - # Extract alias: - - name: 'Extract alias' - id: extract-alias - run: | - alias=$(grep -E 'require\(' README.md | head -n 1 | sed -E 's/^var ([a-zA-Z0-9_]+) = .+/\1/') - echo "alias=${alias}" >> $GITHUB_OUTPUT - - # Create Universal Module Definition (UMD) Node.js bundle: - - name: 'Create Universal Module Definition (UMD) Node.js bundle' - id: umd-bundle-node - uses: stdlib-js/bundle-action@main - with: - target: 'umd-node' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Create Universal Module Definition (UMD) browser bundle: - - name: 'Create Universal Module Definition (UMD) browser bundle' - id: umd-bundle-browser - uses: stdlib-js/bundle-action@main - with: - target: 'umd-browser' - alias: ${{ steps.extract-alias.outputs.alias }} - - # Rewrite file contents: - - name: 'Rewrite file contents' - run: | - # Replace links to other packages with links to the umd branch: - find ./umd -type f -name '*.md' -print0 | xargs -0 sed -Ei "/\/tree\/main/b; /^\[@stdlib[^:]+: https:\/\/github.com\/stdlib-js\// s/(.*)/\\1\/tree\/umd/"; - - # Remove `installation`, `cli`, and `c` sections: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/
[^<]+<\/section>//g;" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.cli \-\->//g" - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/(\* \* \*\n+)?
[\s\S]+<\!\-\- \/.c \-\->//g" - - # Rewrite first `require()` to show consumption of the UMD bundle in Observable and via a `script` tag: - find ./umd -type f -name '*.md' -print0 | xargs -0 perl -0777 -i -pe "s/\`\`\`javascript\n(var|let|const)\s+([a-zA-Z0-9_]+)\s+=\s*require\( '\@stdlib\/([^']+)' \);\n\`\`\`/To use in Observable,\n\n\`\`\`javascript\n\2 = require\( 'https:\/\/cdn.jsdelivr.net\/gh\/stdlib-js\/\3\@umd\/browser.js' \)\n\`\`\`\n\nTo vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:\n\n\`\`\`javascript\nvar \2 = require\( 'path\/to\/vendor\/umd\/\3\/index.js' \)\n\`\`\`\n\nTo include the bundle in a webpage,\n\n\`\`\`html\n + + ```
-
- @@ -266,7 +163,7 @@ b ## Notice -This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. +This package is part of [stdlib][stdlib], a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more. For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib]. @@ -339,9 +236,9 @@ Copyright © 2016-2026. The Stdlib [Authors][stdlib-authors]. -[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first +[@stdlib/string/remove-first]: https://github.com/stdlib-js/string-remove-first/tree/esm -[@stdlib/string/last]: https://github.com/stdlib-js/string-last +[@stdlib/string/last]: https://github.com/stdlib-js/string-last/tree/esm diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9702d4c..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -> Policy for reporting security vulnerabilities. - -See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security). diff --git a/benchmark/benchmark.js b/benchmark/benchmark.js deleted file mode 100644 index 5155d9a..0000000 --- a/benchmark/benchmark.js +++ /dev/null @@ -1,146 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var bench = require( '@stdlib/bench-harness' ); -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var format = require( '@stdlib/string-format' ); -var pkg = require( './../package.json' ).name; -var first = require( './../lib' ); - - -// MAIN // - -bench( pkg, function benchmark( b ) { - var values; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ] ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=grapheme', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'grapheme' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_point', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_point' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - -bench( format( '%s:mode=code_unit', pkg ), function benchmark( b ) { - var values; - var opts; - var out; - var i; - - values = [ - 'beep boop', - 'foo bar', - 'xyz abc' - ]; - opts = { - 'mode': 'code_unit' - }; - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - out = first( values[ i%values.length ], opts ); - if ( typeof out !== 'string' ) { - b.fail( 'should return a string' ); - } - } - b.toc(); - if ( !isString( out ) ) { - b.fail( 'should return a string' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); diff --git a/bin/cli b/bin/cli deleted file mode 100755 index df93741..0000000 --- a/bin/cli +++ /dev/null @@ -1,130 +0,0 @@ -#!/usr/bin/env node - -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var CLI = require( '@stdlib/cli-ctor' ); -var stdin = require( '@stdlib/process-read-stdin' ); -var stdinStream = require( '@stdlib/streams-node-stdin' ); -var RE_EOL = require( '@stdlib/regexp-eol' ).REGEXP; -var isRegExpString = require( '@stdlib/assert-is-regexp-string' ); -var reFromString = require( '@stdlib/utils-regexp-from-string' ); -var first = require( './../lib' ); - - -// MAIN // - -/** -* Main execution sequence. -* -* @private -* @returns {void} -*/ -function main() { - var split; - var flags; - var args; - var opts; - var cli; - var n; - - // Create a command-line interface: - cli = new CLI({ - 'pkg': require( './../package.json' ), - 'options': require( './../etc/cli_opts.json' ), - 'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }) - }); - - // Get any provided command-line options: - flags = cli.flags(); - if ( flags.help || flags.version ) { - return; - } - if ( flags.n ) { - n = parseInt( flags.n, 10 ); - } else { - n = 1; - } - opts = {}; - if ( flags.mode ) { - opts.mode = flags.mode; - } - - // Get any provided command-line arguments: - args = cli.args(); - - // Check if we are receiving data from `stdin`... - if ( !stdinStream.isTTY ) { - if ( flags.split ) { - if ( !isRegExpString( flags.split ) ) { - flags.split = '/'+flags.split+'/'; - } - split = reFromString( flags.split ); - } else { - split = RE_EOL; - } - return stdin( onRead ); - } - try { - console.log( first( args[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - - /** - * Callback invoked upon reading from `stdin`. - * - * @private - * @param {(Error|null)} error - error object - * @param {Buffer} data - data - * @returns {void} - */ - function onRead( error, data ) { - var lines; - var i; - if ( error ) { - return cli.error( error ); - } - lines = data.toString().split( split ); - - // Remove any trailing separators (e.g., trailing newline)... - if ( lines[ lines.length-1 ] === '' ) { - lines.pop(); - } - if ( lines.length ) { - try { - console.log( first( lines[ 0 ], n, opts ) ); // eslint-disable-line no-console - } catch ( error ) { - return cli.error( error ); - } - for ( i = 1; i < lines.length; i++ ) { - console.log( first( lines[ i ], n, opts ) ); // eslint-disable-line no-console - } - } - } -} - -main(); diff --git a/branches.md b/branches.md deleted file mode 100644 index f91d9f7..0000000 --- a/branches.md +++ /dev/null @@ -1,60 +0,0 @@ - - -# Branches - -This repository has the following branches: - -- **main**: default branch generated from the [stdlib project][stdlib-url], where all development takes place. -- **production**: [production build][production-url] of the package (e.g., reformatted error messages to reduce bundle sizes and thus the number of bytes transmitted over a network). -- **esm**: [ES Module][esm-url] branch for use via a `script` tag without the need for installation and bundlers (see [README][esm-readme]). -- **deno**: [Deno][deno-url] branch for use in Deno (see [README][deno-readme]). -- **umd**: [UMD][umd-url] branch for use in Observable, or in dual browser/Node.js environments (see [README][umd-readme]). -- **cli**: [CLI][cli-url] branch for use on the command line. - -The following diagram illustrates the relationships among the above branches: - -```mermaid -graph TD; -A[stdlib]-->|generate standalone package|B; -B[main] -->|productionize| C[production]; -C -->|bundle| D[esm]; -C -->|bundle| E[deno]; -C -->|bundle| F[umd]; -C -->|extract| G[cli]; - -%% click A href "https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first" -%% click B href "https://github.com/stdlib-js/string-first/tree/main" -%% click C href "https://github.com/stdlib-js/string-first/tree/production" -%% click D href "https://github.com/stdlib-js/string-first/tree/esm" -%% click E href "https://github.com/stdlib-js/string-first/tree/deno" -%% click F href "https://github.com/stdlib-js/string-first/tree/umd" -%% click G href "https://github.com/stdlib-js/string-first/tree/cli" -``` - -[stdlib-url]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/string/first -[production-url]: https://github.com/stdlib-js/string-first/tree/production -[deno-url]: https://github.com/stdlib-js/string-first/tree/deno -[deno-readme]: https://github.com/stdlib-js/string-first/blob/deno/README.md -[umd-url]: https://github.com/stdlib-js/string-first/tree/umd -[umd-readme]: https://github.com/stdlib-js/string-first/blob/umd/README.md -[esm-url]: https://github.com/stdlib-js/string-first/tree/esm -[esm-readme]: https://github.com/stdlib-js/string-first/blob/esm/README.md -[cli-url]: https://github.com/stdlib-js/string-first/tree/cli \ No newline at end of file diff --git a/dist/index.d.ts b/dist/index.d.ts deleted file mode 100644 index 5ba531e..0000000 --- a/dist/index.d.ts +++ /dev/null @@ -1,3 +0,0 @@ -/// -import first from '../docs/types/index'; -export = first; \ No newline at end of file diff --git a/dist/index.js b/dist/index.js deleted file mode 100644 index 7d05bad..0000000 --- a/dist/index.js +++ /dev/null @@ -1,5 +0,0 @@ -"use strict";var g=function(i,e){return function(){try{return e||i((e={exports:{}}).exports,e),e.exports}catch(t){throw (e=0, t)}};};var v=g(function(P,m){ -var d=require('@stdlib/assert-is-string/dist').isPrimitive,o=require('@stdlib/assert-is-nonnegative-integer/dist').isPrimitive,s=require('@stdlib/assert-is-plain-object/dist'),f=require('@stdlib/assert-has-own-property/dist'),p=require('@stdlib/array-base-assert-contains/dist').factory,l=require('@stdlib/string-base-first/dist'),c=require('@stdlib/string-base-first-code-point/dist'),h=require('@stdlib/string-base-first-grapheme-cluster/dist'),a=require('@stdlib/error-tools-fmtprodmsg/dist'),u=["grapheme","code_point","code_unit"],w={grapheme:h,code_point:c,code_unit:l},q=p(u);function b(i){var e,t,n,r;if(!d(i))throw new TypeError(a('1gp3F',i));if(n={mode:"grapheme"},t=arguments.length,t===1)r=1;else if(t===2){if(r=arguments[1],s(r))e=r,r=1;else if(!o(r))throw new TypeError(a('1gp3X',r))}else{if(r=arguments[1],!o(r))throw new TypeError(a('1gp3X',r));if(e=arguments[2],!s(e))throw new TypeError(a('1gp2V',e))}if(e&&f(e,"mode")&&(n.mode=e.mode,!q(n.mode)))throw new TypeError(a('1gpE1',"mode",u.join('", "'),n.mode));return w[n.mode](i,r)}m.exports=b -});var y=v();module.exports=y; -/** @license Apache-2.0 */ -//# sourceMappingURL=index.js.map diff --git a/dist/index.js.map b/dist/index.js.map deleted file mode 100644 index 752fa2b..0000000 --- a/dist/index.js.map +++ /dev/null @@ -1,7 +0,0 @@ -{ - "version": 3, - "sources": ["../lib/main.js", "../lib/index.js"], - "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nvar isString = require( '@stdlib/assert-is-string' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar isPlainObject = require( '@stdlib/assert-is-plain-object' );\nvar hasOwnProp = require( '@stdlib/assert-has-own-property' );\nvar contains = require( '@stdlib/array-base-assert-contains' ).factory;\nvar firstCodeUnit = require( '@stdlib/string-base-first' );\nvar firstCodePoint = require( '@stdlib/string-base-first-code-point' );\nvar firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' );\nvar format = require( '@stdlib/string-format' );\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '\uD83D\uDC36\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC30\uD83D\uDC38', 2 );\n* // returns '\uD83D\uDC36\uD83D\uDC2E'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( 'invalid argument. First argument must be a string. Value: `%s`.', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Second argument must be a nonnegative integer. Value: `%s`.', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( 'invalid option. `%s` option must be one of the following: \"%s\". Value: `%s`.', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nmodule.exports = first;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Return the first character(s) of a string.\n*\n* @module @stdlib/string-first\n*\n* @example\n* var first = require( '@stdlib/string-first' );\n*\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* out = first( '\uD83D\uDC2E\uD83D\uDC37\uD83D\uDC38\uD83D\uDC35', 2 );\n* // returns '\uD83D\uDC2E\uD83D\uDC37'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"], - "mappings": "iIAAA,IAAAA,EAAAC,EAAA,SAAAC,EAAAC,EAAA,cAsBA,IAAIC,EAAW,QAAS,0BAA2B,EAAE,YACjDC,EAAuB,QAAS,uCAAwC,EAAE,YAC1EC,EAAgB,QAAS,gCAAiC,EAC1DC,EAAa,QAAS,iCAAkC,EACxDC,EAAW,QAAS,oCAAqC,EAAE,QAC3DC,EAAgB,QAAS,2BAA4B,EACrDC,EAAiB,QAAS,sCAAuC,EACjEC,EAAuB,QAAS,4CAA6C,EAC7EC,EAAS,QAAS,uBAAwB,EAK1CC,EAAQ,CAAE,WAAY,aAAc,WAAY,EAChDC,EAAO,CACV,SAAYH,EACZ,WAAcD,EACd,UAAaD,CACd,EACIM,EAASP,EAAUK,CAAM,EA0C7B,SAASG,EAAOC,EAAM,CACrB,IAAIC,EACAC,EACAC,EACAC,EAEJ,GAAK,CAACjB,EAAUa,CAAI,EACnB,MAAM,IAAI,UAAWL,EAAQ,kEAAmEK,CAAI,CAAE,EAMvG,GAJAG,EAAO,CACN,KAAQ,UACT,EACAD,EAAQ,UAAU,OACbA,IAAU,EACdE,EAAI,UACOF,IAAU,GAErB,GADAE,EAAI,UAAW,CAAE,EACZf,EAAee,CAAE,EACrBH,EAAUG,EACVA,EAAI,UACO,CAAChB,EAAsBgB,CAAE,EACpC,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,MAE7G,CAEN,GADAA,EAAI,UAAW,CAAE,EACZ,CAAChB,EAAsBgB,CAAE,EAC7B,MAAM,IAAI,UAAWT,EAAQ,gFAAiFS,CAAE,CAAE,EAGnH,GADAH,EAAU,UAAW,CAAE,EAClB,CAACZ,EAAeY,CAAQ,EAC5B,MAAM,IAAI,UAAWN,EAAQ,qEAAsEM,CAAQ,CAAE,CAE/G,CACA,GAAKA,GACCX,EAAYW,EAAS,MAAO,IAChCE,EAAK,KAAOF,EAAQ,KACf,CAACH,EAAQK,EAAK,IAAK,GACvB,MAAM,IAAI,UAAWR,EAAQ,+EAAgF,OAAQC,EAAM,KAAM,MAAO,EAAGO,EAAK,IAAK,CAAE,EAI1J,OAAON,EAAMM,EAAK,IAAK,EAAGH,EAAKI,CAAE,CAClC,CAKAlB,EAAO,QAAUa,IC1FjB,IAAIM,EAAO,IAKX,OAAO,QAAUA", - "names": ["require_main", "__commonJSMin", "exports", "module", "isString", "isNonNegativeInteger", "isPlainObject", "hasOwnProp", "contains", "firstCodeUnit", "firstCodePoint", "firstGraphemeCluster", "format", "MODES", "FCNS", "isMode", "first", "str", "options", "nargs", "opts", "n", "main"] -} diff --git a/docs/repl.txt b/docs/repl.txt deleted file mode 100644 index a03fd7a..0000000 --- a/docs/repl.txt +++ /dev/null @@ -1,48 +0,0 @@ - -{{alias}}( str[, n][, options] ) - Returns the first character(s) of a string. - - Parameters - ---------- - str: string - Input string. - - n: integer (optional) - Number of characters to return. Default: 1. - - options: Object (optional) - Options. - - options.mode: string (optional) - Type of characters to return. The following modes are supported: - - - grapheme: grapheme clusters. Appropriate for strings containing visual - characters which can span multiple Unicode code points (e.g., emoji). - - code_point: Unicode code points. Appropriate for strings containing - visual characters which are comprised of more than one Unicode code - unit (e.g., ideographic symbols and punctuation and mathematical - alphanumerics). - - code_unit': UTF-16 code units. Appropriate for strings containing - visual characters drawn from the basic multilingual plane (BMP) (e.g., - common characters, such as those from the Latin, Greek, and Cyrillic - alphabets). - - Default: 'grapheme'. - - Returns - ------- - out: string - Output string. - - Examples - -------- - > var out = {{alias}}( 'beep' ) - 'b' - > out = {{alias}}( 'Boop', 1 ) - 'B' - > out = {{alias}}( 'foo bar', 5 ) - 'foo b' - - See Also - -------- - diff --git a/docs/types/test.ts b/docs/types/test.ts deleted file mode 100644 index 81aaed3..0000000 --- a/docs/types/test.ts +++ /dev/null @@ -1,111 +0,0 @@ -/* -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -import first = require( './index' ); - - -// TESTS // - -// The function returns a string... -{ - first( 'abc' ); // $ExpectType string - first( 'abc', 1 ); // $ExpectType string - first( 'abc', {} ); // $ExpectType string - first( 'abc', 1, {} ); // $ExpectType string -} - -// The compiler throws an error if the function is provided a first argument which is not a string... -{ - first( true ); // $ExpectError - first( false ); // $ExpectError - first( null ); // $ExpectError - first( undefined ); // $ExpectError - first( 5 ); // $ExpectError - first( [] ); // $ExpectError - first( {} ); // $ExpectError - first( ( x: number ): number => x ); // $ExpectError - - first( true, 1 ); // $ExpectError - first( false, 1 ); // $ExpectError - first( null, 1 ); // $ExpectError - first( undefined, 1 ); // $ExpectError - first( 5, 1 ); // $ExpectError - first( [], 1 ); // $ExpectError - first( {}, 1 ); // $ExpectError - first( ( x: number ): number => x, 1 ); // $ExpectError - - first( true, {} ); // $ExpectError - first( false, {} ); // $ExpectError - first( null, {} ); // $ExpectError - first( undefined, {} ); // $ExpectError - first( 5, {} ); // $ExpectError - first( [], {} ); // $ExpectError - first( {}, {} ); // $ExpectError - first( ( x: number ): number => x, {} ); // $ExpectError - - first( true, 1, {} ); // $ExpectError - first( false, 1, {} ); // $ExpectError - first( null, 1, {} ); // $ExpectError - first( undefined, 1, {} ); // $ExpectError - first( 5, 1, {} ); // $ExpectError - first( [], 1, {} ); // $ExpectError - first( {}, 1, {} ); // $ExpectError - first( ( x: number ): number => x, 1, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid second argument... -{ - first( 'abc', true ); // $ExpectError - first( 'abc', false ); // $ExpectError - first( 'abc', null ); // $ExpectError - first( 'abc', '' ); // $ExpectError - first( 'abc', [] ); // $ExpectError - first( 'abc', ( x: number ): number => x ); // $ExpectError - - first( 'abc', true, {} ); // $ExpectError - first( 'abc', false, {} ); // $ExpectError - first( 'abc', null, {} ); // $ExpectError - first( 'abc', '', {} ); // $ExpectError - first( 'abc', [], {} ); // $ExpectError - first( 'abc', {}, {} ); // $ExpectError - first( 'abc', ( x: number ): number => x, {} ); // $ExpectError -} - -// The compiler throws an error if the function is provided an invalid `mode` option... -{ - first( 'abc', { 'mode': true } ); // $ExpectError - first( 'abc', { 'mode': false } ); // $ExpectError - first( 'abc', { 'mode': null } ); // $ExpectError - first( 'abc', { 'mode': '' } ); // $ExpectError - first( 'abc', { 'mode': [] } ); // $ExpectError - first( 'abc', { 'mode': ( x: number ): number => x } ); // $ExpectError - - first( 'abc', 1, { 'mode': true } ); // $ExpectError - first( 'abc', 1, { 'mode': false } ); // $ExpectError - first( 'abc', 1, { 'mode': null } ); // $ExpectError - first( 'abc', 1, { 'mode': '' } ); // $ExpectError - first( 'abc', 1, { 'mode': [] } ); // $ExpectError - first( 'abc', 1, { 'mode': {} } ); // $ExpectError - first( 'abc', 1, { 'mode': ( x: number ): number => x } ); // $ExpectError -} - -// The compiler throws an error if the function is provided an unsupported number of arguments... -{ - first(); // $ExpectError - first( 'abc', 1, {}, {} ); // $ExpectError -} diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index 6b23473..0000000 --- a/docs/usage.txt +++ /dev/null @@ -1,10 +0,0 @@ - -Usage: first [options] [] - -Options: - - -h, --help Print this message. - -V, --version Print the package version. - --n num Number of characters to return. Default: 1. - --split sep Delimiter for stdin data. Default: '/\\r?\\n/'. - --mode mode Type of character to return. Default: 'grapheme'. diff --git a/etc/cli_opts.json b/etc/cli_opts.json deleted file mode 100644 index 2ceae45..0000000 --- a/etc/cli_opts.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "boolean": [ - "help", - "version" - ], - "string": [ - "n", - "split", - "mode" - ], - "alias": { - "help": [ - "h" - ], - "version": [ - "V" - ] - } -} diff --git a/examples/index.js b/examples/index.js deleted file mode 100644 index e63828c..0000000 --- a/examples/index.js +++ /dev/null @@ -1,42 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -var first = require( './../lib' ); - -console.log( first( 'last man standing' ) ); -// => 'l' - -console.log( first( 'presidential election' ) ); -// => 'p' - -console.log( first( 'javaScript' ) ); -// => 'j' - -console.log( first( 'Hidden Treasures' ) ); -// => 'H' - -console.log( first( 'The Last of the Mohicans', 5 ) ); -// => 'The L' - -console.log( first( '🐶🐮🐷🐰🐸', 2 ) ); -// => '🐶🐮' - -console.log( first( '🐶🐮🐷🐰🐸', 10 ) ); -// => '🐶🐮🐷🐰🐸' diff --git a/docs/types/index.d.ts b/index.d.ts similarity index 100% rename from docs/types/index.d.ts rename to index.d.ts diff --git a/index.mjs b/index.mjs new file mode 100644 index 0000000..afaf1ca --- /dev/null +++ b/index.mjs @@ -0,0 +1,4 @@ +// Copyright (c) 2026 The Stdlib Authors. License is Apache-2.0: http://www.apache.org/licenses/LICENSE-2.0 +/// +import{isPrimitive as e}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-string@v0.2.3-esm/index.mjs";import{isPrimitive as s}from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-nonnegative-integer@v0.2.3-esm/index.mjs";import t from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-is-plain-object@v0.2.3-esm/index.mjs";import r from"https://cdn.jsdelivr.net/gh/stdlib-js/assert-has-own-property@v0.2.3-esm/index.mjs";import{factory as i}from"https://cdn.jsdelivr.net/gh/stdlib-js/array-base-assert-contains@v0.2.3-esm/index.mjs";import o from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first@v0.2.3-esm/index.mjs";import n from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-code-point@v0.2.3-esm/index.mjs";import d from"https://cdn.jsdelivr.net/gh/stdlib-js/string-base-first-grapheme-cluster@v0.2.3-esm/index.mjs";import m from"https://cdn.jsdelivr.net/gh/stdlib-js/error-tools-fmtprodmsg@v0.2.3-esm/index.mjs";var p=["grapheme","code_point","code_unit"],h={grapheme:d,code_point:n,code_unit:o},j=i(p);function g(i){var o,n,d,g;if(!e(i))throw new TypeError(m("1gp3F",i));if(d={mode:"grapheme"},1===(n=arguments.length))g=1;else if(2===n){if(t(g=arguments[1]))o=g,g=1;else if(!s(g))throw new TypeError(m("1gp3X",g))}else{if(!s(g=arguments[1]))throw new TypeError(m("1gp3X",g));if(!t(o=arguments[2]))throw new TypeError(m("1gp2V",o))}if(o&&r(o,"mode")&&(d.mode=o.mode,!j(d.mode)))throw new TypeError(m("1gpE1","mode",p.join('", "'),d.mode));return h[d.mode](i,g)}export{g as default}; +//# sourceMappingURL=index.mjs.map diff --git a/index.mjs.map b/index.mjs.map new file mode 100644 index 0000000..4d2dc9f --- /dev/null +++ b/index.mjs.map @@ -0,0 +1 @@ +{"version":3,"file":"index.mjs","sources":["../lib/main.js"],"sourcesContent":["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2023 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n* http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n// MODULES //\n\nimport { isPrimitive as isString } from '@stdlib/assert-is-string';\nimport { isPrimitive as isNonNegativeInteger } from '@stdlib/assert-is-nonnegative-integer';\nimport isPlainObject from '@stdlib/assert-is-plain-object';\nimport hasOwnProp from '@stdlib/assert-has-own-property';\nimport { factory as contains } from '@stdlib/array-base-assert-contains';\nimport firstCodeUnit from '@stdlib/string-base-first';\nimport firstCodePoint from '@stdlib/string-base-first-code-point';\nimport firstGraphemeCluster from '@stdlib/string-base-first-grapheme-cluster';\nimport format from '@stdlib/error-tools-fmtprodmsg';\n\n\n// VARIABLES //\n\nvar MODES = [ 'grapheme', 'code_point', 'code_unit' ];\nvar FCNS = {\n\t'grapheme': firstGraphemeCluster,\n\t'code_point': firstCodePoint,\n\t'code_unit': firstCodeUnit\n};\nvar isMode = contains( MODES );\n\n\n// MAIN //\n\n/**\n* Returns the first character(s) of a string.\n*\n* @param {string} str - input string\n* @param {NonNegativeInteger} [n=1] - number of characters to return\n* @param {Options} [options] - options\n* @param {string} [options.mode=\"grapheme\"] - type of \"character\" to return (must be either `grapheme`, `code_point`, or `code_unit`)\n* @throws {TypeError} first argument must be a string\n* @throws {TypeError} second argument must be a nonnegative integer\n* @throws {TypeError} options argument must be an object\n* @throws {TypeError} must provide valid options\n* @returns {string} output string\n*\n* @example\n* var out = first( 'last man standing' );\n* // returns 'l'\n*\n* @example\n* var out = first( 'presidential election' );\n* // returns 'p'\n*\n* @example\n* var out = first( 'javaScript' );\n* // returns 'j'\n*\n* @example\n* var out = first( 'Hidden Treasures' );\n* // returns 'H'\n*\n* @example\n* var out = first( '🐶🐮🐷🐰🐸', 2 );\n* // returns '🐶🐮'\n*\n* @example\n* var out = first( 'foo bar', 5 );\n* // returns 'foo b'\n*/\nfunction first( str ) {\n\tvar options;\n\tvar nargs;\n\tvar opts;\n\tvar n;\n\n\tif ( !isString( str ) ) {\n\t\tthrow new TypeError( format( '1gp3F', str ) );\n\t}\n\topts = {\n\t\t'mode': 'grapheme'\n\t};\n\tnargs = arguments.length;\n\tif ( nargs === 1 ) {\n\t\tn = 1;\n\t} else if ( nargs === 2 ) {\n\t\tn = arguments[ 1 ];\n\t\tif ( isPlainObject( n ) ) {\n\t\t\toptions = n;\n\t\t\tn = 1;\n\t\t} else if ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t} else { // nargs > 2\n\t\tn = arguments[ 1 ];\n\t\tif ( !isNonNegativeInteger( n ) ) {\n\t\t\tthrow new TypeError( format( '1gp3X', n ) );\n\t\t}\n\t\toptions = arguments[ 2 ];\n\t\tif ( !isPlainObject( options ) ) {\n\t\t\tthrow new TypeError( format( '1gp2V', options ) );\n\t\t}\n\t}\n\tif ( options ) {\n\t\tif ( hasOwnProp( options, 'mode' ) ) {\n\t\t\topts.mode = options.mode;\n\t\t\tif ( !isMode( opts.mode ) ) {\n\t\t\t\tthrow new TypeError( format( '1gpE1', 'mode', MODES.join( '\", \"' ), opts.mode ) );\n\t\t\t}\n\t\t}\n\t}\n\treturn FCNS[ opts.mode ]( str, n );\n}\n\n\n// EXPORTS //\n\nexport default first;\n"],"names":["MODES","FCNS","grapheme","firstGraphemeCluster","code_point","firstCodePoint","code_unit","firstCodeUnit","isMode","contains","first","str","options","nargs","opts","n","isString","TypeError","format","mode","arguments","length","isPlainObject","isNonNegativeInteger","hasOwnProp","join"],"mappings":";;q6BAmCA,IAAIA,EAAQ,CAAE,WAAY,aAAc,aACpCC,EAAO,CACVC,SAAYC,EACZC,WAAcC,EACdC,UAAaC,GAEVC,EAASC,EAAUT,GA0CvB,SAASU,EAAOC,GACf,IAAIC,EACAC,EACAC,EACAC,EAEJ,IAAMC,EAAUL,GACf,MAAM,IAAIM,UAAWC,EAAQ,QAASP,IAMvC,GAJAG,EAAO,CACNK,KAAQ,YAGM,KADfN,EAAQO,UAAUC,QAEjBN,EAAI,OACE,GAAe,IAAVF,GAEX,GAAKS,EADLP,EAAIK,UAAW,IAEdR,EAAUG,EACVA,EAAI,OACE,IAAMQ,EAAsBR,GAClC,MAAM,IAAIE,UAAWC,EAAQ,QAASH,QAEjC,CAEN,IAAMQ,EADNR,EAAIK,UAAW,IAEd,MAAM,IAAIH,UAAWC,EAAQ,QAASH,IAGvC,IAAMO,EADNV,EAAUQ,UAAW,IAEpB,MAAM,IAAIH,UAAWC,EAAQ,QAASN,GAEvC,CACD,GAAKA,GACCY,EAAYZ,EAAS,UACzBE,EAAKK,KAAOP,EAAQO,MACdX,EAAQM,EAAKK,OAClB,MAAM,IAAIF,UAAWC,EAAQ,QAAS,OAAQlB,EAAMyB,KAAM,QAAUX,EAAKK,OAI5E,OAAOlB,EAAMa,EAAKK,MAAQR,EAAKI,EAChC"} \ No newline at end of file diff --git a/lib/index.js b/lib/index.js deleted file mode 100644 index 6b45bb3..0000000 --- a/lib/index.js +++ /dev/null @@ -1,46 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -/** -* Return the first character(s) of a string. -* -* @module @stdlib/string-first -* -* @example -* var first = require( '@stdlib/string-first' ); -* -* var out = first( 'last man standing' ); -* // returns 'l' -* -* out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* out = first( '🐮🐷🐸🐵', 2 ); -* // returns '🐮🐷' -*/ - -// MODULES // - -var main = require( './main.js' ); - - -// EXPORTS // - -module.exports = main; diff --git a/lib/main.js b/lib/main.js deleted file mode 100644 index 27fe5b8..0000000 --- a/lib/main.js +++ /dev/null @@ -1,131 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var isString = require( '@stdlib/assert-is-string' ).isPrimitive; -var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive; -var isPlainObject = require( '@stdlib/assert-is-plain-object' ); -var hasOwnProp = require( '@stdlib/assert-has-own-property' ); -var contains = require( '@stdlib/array-base-assert-contains' ).factory; -var firstCodeUnit = require( '@stdlib/string-base-first' ); -var firstCodePoint = require( '@stdlib/string-base-first-code-point' ); -var firstGraphemeCluster = require( '@stdlib/string-base-first-grapheme-cluster' ); -var format = require( '@stdlib/error-tools-fmtprodmsg' ); - - -// VARIABLES // - -var MODES = [ 'grapheme', 'code_point', 'code_unit' ]; -var FCNS = { - 'grapheme': firstGraphemeCluster, - 'code_point': firstCodePoint, - 'code_unit': firstCodeUnit -}; -var isMode = contains( MODES ); - - -// MAIN // - -/** -* Returns the first character(s) of a string. -* -* @param {string} str - input string -* @param {NonNegativeInteger} [n=1] - number of characters to return -* @param {Options} [options] - options -* @param {string} [options.mode="grapheme"] - type of "character" to return (must be either `grapheme`, `code_point`, or `code_unit`) -* @throws {TypeError} first argument must be a string -* @throws {TypeError} second argument must be a nonnegative integer -* @throws {TypeError} options argument must be an object -* @throws {TypeError} must provide valid options -* @returns {string} output string -* -* @example -* var out = first( 'last man standing' ); -* // returns 'l' -* -* @example -* var out = first( 'presidential election' ); -* // returns 'p' -* -* @example -* var out = first( 'javaScript' ); -* // returns 'j' -* -* @example -* var out = first( 'Hidden Treasures' ); -* // returns 'H' -* -* @example -* var out = first( '🐶🐮🐷🐰🐸', 2 ); -* // returns '🐶🐮' -* -* @example -* var out = first( 'foo bar', 5 ); -* // returns 'foo b' -*/ -function first( str ) { - var options; - var nargs; - var opts; - var n; - - if ( !isString( str ) ) { - throw new TypeError( format( '1gp3F', str ) ); - } - opts = { - 'mode': 'grapheme' - }; - nargs = arguments.length; - if ( nargs === 1 ) { - n = 1; - } else if ( nargs === 2 ) { - n = arguments[ 1 ]; - if ( isPlainObject( n ) ) { - options = n; - n = 1; - } else if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - } else { // nargs > 2 - n = arguments[ 1 ]; - if ( !isNonNegativeInteger( n ) ) { - throw new TypeError( format( '1gp3X', n ) ); - } - options = arguments[ 2 ]; - if ( !isPlainObject( options ) ) { - throw new TypeError( format( '1gp2V', options ) ); - } - } - if ( options ) { - if ( hasOwnProp( options, 'mode' ) ) { - opts.mode = options.mode; - if ( !isMode( opts.mode ) ) { - throw new TypeError( format( '1gpE1', 'mode', MODES.join( '", "' ), opts.mode ) ); - } - } - } - return FCNS[ opts.mode ]( str, n ); -} - - -// EXPORTS // - -module.exports = first; diff --git a/package.json b/package.json index 5868346..49167c4 100644 --- a/package.json +++ b/package.json @@ -3,34 +3,8 @@ "version": "0.2.3", "description": "Return the first character(s) of a string.", "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "bin": { - "first": "./bin/cli" - }, - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": { - "test": "make test", - "test-cov": "make test-cov", - "examples": "make examples", - "benchmark": "make benchmark" - }, + "type": "module", + "main": "./index.mjs", "homepage": "https://stdlib.io", "repository": { "type": "git", @@ -39,51 +13,6 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/array-base-assert-contains": "^0.2.3", - "@stdlib/assert-has-own-property": "^0.2.3", - "@stdlib/assert-is-nonnegative-integer": "^0.2.3", - "@stdlib/assert-is-plain-object": "^0.2.3", - "@stdlib/assert-is-regexp-string": "^0.2.3", - "@stdlib/assert-is-string": "^0.2.3", - "@stdlib/cli-ctor": "^0.2.3", - "@stdlib/fs-read-file": "^0.2.3", - "@stdlib/process-read-stdin": "^0.2.3", - "@stdlib/regexp-eol": "^0.2.3", - "@stdlib/streams-node-stdin": "^0.2.3", - "@stdlib/string-base-first": "^0.2.3", - "@stdlib/string-base-first-code-point": "^0.2.3", - "@stdlib/string-base-first-grapheme-cluster": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3", - "@stdlib/utils-regexp-from-string": "^0.2.3", - "@stdlib/error-tools-fmtprodmsg": "^0.2.3" - }, - "devDependencies": { - "@stdlib/assert-is-browser": "^0.2.3", - "@stdlib/assert-is-windows": "^0.2.3", - "@stdlib/process-exec-path": "^0.2.3", - "@stdlib/string-replace": "^0.2.3", - "tape": "git+https://github.com/kgryte/tape.git#fix/globby", - "proxyquire": "^2.0.0", - "istanbul": "^0.4.1", - "tap-min": "git+https://github.com/Planeshifter/tap-min.git", - "@stdlib/bench-harness": "^0.2.3" - }, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], "keywords": [ "stdlib", "stdstring", diff --git a/stats.html b/stats.html new file mode 100644 index 0000000..7cca235 --- /dev/null +++ b/stats.html @@ -0,0 +1,4842 @@ + + + + + + + + Rollup Visualizer + + + +
+ + + + + diff --git a/test/dist/test.js b/test/dist/test.js deleted file mode 100644 index a8a9c60..0000000 --- a/test/dist/test.js +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var main = require( './../../dist' ); - - -// TESTS // - -tape( 'main export is defined', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( main !== void 0, true, 'main export is defined' ); - t.end(); -}); diff --git a/test/fixtures/stdin_error.js.txt b/test/fixtures/stdin_error.js.txt deleted file mode 100644 index 7d9e68d..0000000 --- a/test/fixtures/stdin_error.js.txt +++ /dev/null @@ -1,33 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -var proc = require( 'process' ); -var resolve = require( 'path' ).resolve; -var proxyquire = require( 'proxyquire' ); - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); - -proc.stdin.isTTY = false; - -proxyquire( fpath, { - '@stdlib/process-read-stdin': stdin -}); - -function stdin( clbk ) { - clbk( new Error( 'beep' ) ); -} diff --git a/test/test.cli.js b/test/test.cli.js deleted file mode 100644 index 76576ad..0000000 --- a/test/test.cli.js +++ /dev/null @@ -1,389 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var resolve = require( 'path' ).resolve; -var exec = require( 'child_process' ).exec; -var tape = require( 'tape' ); -var IS_BROWSER = require( '@stdlib/assert-is-browser' ); -var IS_WINDOWS = require( '@stdlib/assert-is-windows' ); -var replace = require( '@stdlib/string-replace' ); -var readFileSync = require( '@stdlib/fs-read-file' ).sync; -var EXEC_PATH = require( '@stdlib/process-exec-path' ); - - -// VARIABLES // - -var fpath = resolve( __dirname, '..', 'bin', 'cli' ); -var opts = { - 'skip': IS_BROWSER || IS_WINDOWS -}; - - -// FIXTURES // - -var PKG_VERSION = require( './../package.json' ).version; - - -// TESTS // - -tape( 'command-line interface', function test( t ) { - t.ok( true, __filename ); - t.end(); -}); - -tape( 'when invoked with a `--help` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '--help' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-h` flag, the command-line interface prints the help text to `stderr`', opts, function test( t ) { - var expected; - var cmd; - - expected = readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), { - 'encoding': 'utf8' - }); - cmd = [ - EXEC_PATH, - fpath, - '-h' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), expected+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `--version` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '--version' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'when invoked with a `-V` flag, the command-line interface prints the version to `stderr`', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - fpath, - '-V' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), PKG_VERSION+'\n', 'expected value' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first character of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface returns the first `n` characters of a string argument', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--n=2\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'be\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=code_point\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - EXEC_PATH, - '-e', - '"process.stdin.isTTY = true; process.argv[ 2 ] = \'beep\'; process.argv[ 3 ] = \'--mode=foo\'; require( \''+fpath+'\' );"' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf "beep\nboop"', - '|', - EXEC_PATH, - fpath - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'b\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports use as a standard stream (return `n` characters)', opts, function test( t ) { - var cmd = [ - 'printf "foo\nbar"', - '|', - EXEC_PATH, - fpath, - '--n=2' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'fo\nba\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (string)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split \'\t\'' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying the type of characters to return when used as a standard stream', opts, function test( t ) { - var cmd = [ - 'printf \'foo\nbar\nbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode code_point' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'the command-line interface supports specifying a custom delimiter when used as a standard stream (regexp)', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--split=/\\\\t/' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.fail( error.message ); - } else { - t.strictEqual( stdout.toString(), 'f\nb\nb\n', 'expected value' ); - t.strictEqual( stderr.toString(), '', 'does not print to `stderr`' ); - } - t.end(); - } -}); - -tape( 'when used as a standard stream, if provided an invalid option, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var cmd = [ - 'printf \'foo\tbar\tbaz\'', - '|', - EXEC_PATH, - fpath, - '--mode=foo' - ]; - - exec( cmd.join( ' ' ), done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString().length > 0, true, 'expected value' ); - t.end(); - } -}); - -tape( 'when used as a standard stream, if an error is encountered when reading from `stdin`, the command-line interface prints an error and sets a non-zero exit code', opts, function test( t ) { - var script; - var opts; - var cmd; - - script = readFileSync( resolve( __dirname, 'fixtures', 'stdin_error.js.txt' ), { - 'encoding': 'utf8' - }); - - // Replace single quotes with double quotes: - script = replace( script, '\'', '"' ); - - cmd = [ - EXEC_PATH, - '-e', - '\''+script+'\'' - ]; - - opts = { - 'cwd': __dirname - }; - - exec( cmd.join( ' ' ), opts, done ); - - function done( error, stdout, stderr ) { - if ( error ) { - t.pass( error.message ); - t.strictEqual( error.code, 1, 'expected exit code' ); - } - t.strictEqual( stdout.toString(), '', 'does not print to `stdout`' ); - t.strictEqual( stderr.toString(), 'Error: beep\n', 'expected value' ); - t.end(); - } -}); diff --git a/test/test.js b/test/test.js deleted file mode 100644 index 912a1ab..0000000 --- a/test/test.js +++ /dev/null @@ -1,406 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2023 The Stdlib Authors. -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - -'use strict'; - -// MODULES // - -var tape = require( 'tape' ); -var first = require( './../lib' ); - - -// TESTS // - -tape( 'main export is a function', function test( t ) { - t.ok( true, __filename ); - t.strictEqual( typeof first, 'function', 'main export is a function' ); - t.end(); -}); - -tape( 'the function throws an error if not provided a string', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value ); - }; - } -}); - -tape( 'the function throws an error if not provided a string (options)', function test( t ) { - var values; - var i; - - values = [ - 5, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value ); - }; - } -}); - -tape( 'the function throws an error if provided a second argument which is not a nonnegative integer (options)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3.14, - null, - true, - void 0, - NaN, - [], - {}, - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', value, {} ); - }; - } -}); - -tape( 'the function throws an error if provided an options argument which is not an object', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, value ); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (second argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', { - 'mode': value - }); - }; - } -}); - -tape( 'the function throws an error if provided a `mode` option which is not a supported mode (third argument)', function test( t ) { - var values; - var i; - - values = [ - 'abc', - 3, - null, - true, - void 0, - NaN, - [], - function noop() {} - ]; - - for ( i = 0; i < values.length; i++ ) { - t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); - } - t.end(); - - function badValue( value ) { - return function badValue() { - first( 'beep', 1, { - 'mode': value - }); - }; - } -}); - -tape( 'the function returns an empty string if provided an empty string', function test( t ) { - t.strictEqual( first( '' ), '', 'returns expected value' ); - t.strictEqual( first( '', 1 ), '', 'returns expected value' ); - t.strictEqual( first( '', {} ), '', 'returns expected value' ); - t.strictEqual( first( '', 1, {} ), '', 'returns expected value' ); - t.end(); -}); - -tape( 'the function returns the first character of a provided string', function test( t ) { - var out; - - out = first( 'hello world' ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( '!!!' ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( 'Hello World' ); - t.strictEqual( out, 'H', 'returns expected value' ); - - out = first( 'अनुच्छेद' ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書' ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷' ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function returns an empty string if provided zero as the second argument', function test( t ) { - var out; - - out = first( 'hello world', 0 ); - t.strictEqual( out, '', 'returns expected value' ); - - out = first( 'hello world', 0, {} ); - t.strictEqual( out, '', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (default)', function test( t ) { - var out; - - out = first( 'hello world', 1 ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7 ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1 ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2 ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1 ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1 ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1 ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1 ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=grapheme)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'grapheme' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉🏿', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_point)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_point' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '🌷', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '👉', 'returns expected value' ); - - t.end(); -}); - -tape( 'the function supports returning the first `n` characters of a provided string (mode=code_unit)', function test( t ) { - var opts; - var out; - - opts = { - 'mode': 'code_unit' - }; - - out = first( 'hello world', 1, opts ); - t.strictEqual( out, 'h', 'returns expected value' ); - - out = first( 'hello world', 7, opts ); - t.strictEqual( out, 'hello w', 'returns expected value' ); - - out = first( '!!!', 1, opts ); - t.strictEqual( out, '!', 'returns expected value' ); - - out = first( '!!!', 2, opts ); - t.strictEqual( out, '!!', 'returns expected value' ); - - out = first( 'अनुच्छेद', 1, opts ); - t.strictEqual( out, 'अ', 'returns expected value' ); - - out = first( '六书/六書', 1, opts ); - t.strictEqual( out, '六', 'returns expected value' ); - - out = first( '🌷', 1, opts ); - t.strictEqual( out, '\ud83c', 'returns expected value' ); - - out = first( '👉🏿', 1, opts ); - t.strictEqual( out, '\ud83d', 'returns expected value' ); - - t.end(); -});