diff --git a/.gitignore b/.gitignore index 35689ee..ea546e7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,62 +1,110 @@ +# macOS-specific files .DS_Store + +# Windows-specific files Thumbs.db + +# Jetbrains specific files .idea + +# Environment variables .env +.env.local .env.development.local .env.test.local .env.production.local -.env.local -_scratch* -logs -_.log + +# Node modules and logs +node_modules/ npm-debug.log_ yarn-debug.log* yarn-error.log* lerna-debug.log* .pnpm-debug.log* .cache +*.tgz +.yarn-integrity +.parcel-cache +.next +.out +.nuxt +.dist +.vuepress/dist +.temp +.docusaurus +.serverless/ +.fusebox/ +.dynamodb/ +.tern-port +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + +# Debug logs +_scratch* +logs +_.log + +# Report files report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json + +# Process IDs pids _.pid _.seed *.pid.lock + +# Coverage reports lib-cov coverage *.lcov .nyc_output + +# Grunt intermediate storage .grunt + +# Bower components bower_components + +# Node-waf configuration .lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) build/Release -node_modules/ + +# JSPM packages jspm_packages/ + +# Web modules web_modules/ + +# TypeScript build info *.tsbuildinfo + +# NPM debug logs .npm + +# Linter caches .eslintcache .stylelintcache + +# Rollup plugin caches .rpt2_cache/ .rts2_cache_cjs/ .rts2_cache_es/ .rts2_cache_umd/ + +# Node.js REPL history .node_repl_history -*.tgz -.yarn-integrity -.parcel-cache -.next -out -.nuxt -dist -.vuepress/dist -.temp -.docusaurus -.serverless/ -.fusebox/ -.dynamodb/ -.tern-port -.yarn/cache -.yarn/unplugged -.yarn/build-state.yml -.yarn/install-state.gz -.pnp.* + +# Visual Studio Code +.vscode .vscode-test + +# generated types from Astro +.astro/ + +# Astro's build output +dist/ diff --git a/README.md b/README.md index 0382a85..a23f9ee 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![sloth-pipe](readme-banner.png) +![sloth-pipe](/docs/src/assets/readme-banner.png) # Sloth Pipe diff --git a/bun.lockb b/bun.lockb index 70ec2af..59918e8 100755 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b51abaa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,54 @@ +# Starlight Starter Kit: Basics + +[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) + +``` +npm create astro@latest -- --template starlight +``` + +[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics) +[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics) +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs) + +> πŸ§‘β€πŸš€ **Seasoned astronaut?** Delete this file. Have fun! + +## πŸš€ Project Structure + +Inside of your Astro + Starlight project, you'll see the following folders and files: + +``` +. +β”œβ”€β”€ public/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ assets/ +β”‚ β”œβ”€β”€ content/ +β”‚ β”‚ β”œβ”€β”€ docs/ +β”‚ β”‚ └── config.ts +β”‚ └── env.d.ts +β”œβ”€β”€ astro.config.mjs +β”œβ”€β”€ package.json +└── tsconfig.json +``` + +Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. + +Images can be added to `src/assets/` and embedded in Markdown with a relative link. + +Static assets, like favicons, can be placed in the `public/` directory. + +## 🧞 Commands + +All commands are run from the root of the project, from a terminal: + +| Command | Action | +| :------------------------ | :----------------------------------------------- | +| `npm install` | Installs dependencies | +| `npm run dev` | Starts local dev server at `localhost:4321` | +| `npm run build` | Build your production site to `./dist/` | +| `npm run preview` | Preview your build locally, before deploying | +| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | +| `npm run astro -- --help` | Get help using the Astro CLI | + +## πŸ‘€ Want to learn more? + +Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs new file mode 100644 index 0000000..1ecbafb --- /dev/null +++ b/docs/astro.config.mjs @@ -0,0 +1,64 @@ +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +/* https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables */ +const VERCEL_PREVIEW_SITE = + process.env.VERCEL_ENV !== 'production' && + process.env.VERCEL_URL && + `https://${process.env.VERCEL_URL}`; + +//TODO: Fix this +const site = VERCEL_PREVIEW_SITE || 'https://slothpipe.techsavvytravvy.com/'; + + +// https://astro.build/config +export default defineConfig({ + integrations: [ + starlight({ + title: 'Sloth Pipe', + social: { + github: 'https://github.com/trvswgnr/sloth-pipe', + "x.com": "https://twitter.com/techsavvytravvy", + }, + favicon: '/public/favicon.ico', + head: [ + { + tag: 'meta', + attrs: { property: 'og:image', content: site + 'og.jpg?v=1' }, + }, + { + tag: 'meta', + attrs: { property: 'twitter:image', content: site + 'og.jpg?v=1' }, + }, + ], + customCss: [ + // Relative path to your custom CSS file + './src/styles/custom.css', + ], + editLink: { + baseUrl: + "https://github.com/trvswgnr/sloth-pipe/edit/main/docs/", + }, + lastUpdated: true, + sidebar: [ + { + label: 'Getting started', + items: [ + { label: 'Why Sloth Pipe?', link: '/getting-started/why/' }, + { label: 'Installation', link: '/getting-started/installation/' }, + { label: 'Usage', link: '/getting-started/usage/' }, + ], + }, + { + label: 'Reference', + items: [ + { label: 'Pipe Function', link: '/reference/pipe-function/' }, + { label: 'Methods', link: '/reference/methods/' }, + { label: 'Error Handling', link: '/reference/error-handling/' }, + { label: 'Async Await Support', link: '/reference/async-await-support/' }, + ], + }, + ], + }), + ], +}); diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..5ac7798 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,19 @@ +{ + "name": "docs", + "type": "module", + "version": "0.0.1", + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro check && astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/starlight": "^0.17.2", + "astro": "^4.2.1", + "sharp": "^0.32.5", + "@astrojs/check": "^0.4.1", + "typescript": "^5.3.3" + } +} \ No newline at end of file diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico new file mode 100644 index 0000000..09870c2 Binary files /dev/null and b/docs/public/favicon.ico differ diff --git a/docs/public/og.jpg b/docs/public/og.jpg new file mode 100644 index 0000000..7340581 Binary files /dev/null and b/docs/public/og.jpg differ diff --git a/readme-banner.png b/docs/src/assets/readme-banner.png similarity index 100% rename from readme-banner.png rename to docs/src/assets/readme-banner.png diff --git a/docs/src/content/config.ts b/docs/src/content/config.ts new file mode 100644 index 0000000..822438e --- /dev/null +++ b/docs/src/content/config.ts @@ -0,0 +1,7 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), +}; diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx new file mode 100644 index 0000000..2253d44 --- /dev/null +++ b/docs/src/content/docs/getting-started/installation.mdx @@ -0,0 +1,32 @@ +--- +title: Installation +description: Learn how to install sloth-pipe in your project. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Add `sloth-pipe` to your project using your favorite package manager: + + + + ```bash + npm install sloth-pipe + ``` + + + ```bash + yarn add sloth-pipe + ``` + + + ```bash + pnpm add sloth-pipe + ``` + + + ```bash + bun install sloth-pipe + ``` + + + diff --git a/docs/src/content/docs/getting-started/usage.mdx b/docs/src/content/docs/getting-started/usage.mdx new file mode 100644 index 0000000..8b0e766 --- /dev/null +++ b/docs/src/content/docs/getting-started/usage.mdx @@ -0,0 +1,59 @@ +--- +title: Usage +description: Learn how to use sloth-pipe in your projects. +--- + +Sloth Pipe is a functional library designed to streamline the process of applying a sequence of +transformations to a value in TypeScript. It enables chaining multiple operations in a clear and +readable manner. + +## Importing the Library + +Begin by importing the Pipe function from the sloth-pipe library: + +```ts +import { Pipe } from "sloth-pipe"; +``` + +## Initializing the Pipe + +Create a new pipe instance by calling Pipe() with the initial value. This value is the starting +point for subsequent transformations: + +```ts +const pipeInstance = Pipe(5); +``` + +## Applying Transformations + +Use the .to() method to define transformations. Each .to() takes a function as an argument. This +function describes how the current value should be transformed: + +The first transformation multiplies the input by 2: + +```ts +.to((x) => x * 2) +``` + +The second transformation adds 3 to the result of the first transformation: + +```ts +.to((x) => x + 3) +``` + +## Executing the Pipe + +Complete the chain of transformations with the .exec() method. This method executes the +transformations in sequence and returns the final result: + +```ts +const result = pipeInstance.exec(); +``` + +## Output: + +The final result can be used as needed. In this example, it's logged to the console: + +```ts +console.log(result); // Outputs: 13 +``` diff --git a/docs/src/content/docs/getting-started/why.mdx b/docs/src/content/docs/getting-started/why.mdx new file mode 100644 index 0000000..041c5aa --- /dev/null +++ b/docs/src/content/docs/getting-started/why.mdx @@ -0,0 +1,30 @@ +--- +title: Why Sloth Pipe? +description: Why should you use Sloth Pipe? +--- + +Developers want pipes. They've been one of the +[most requested features](https://2020.stateofjs.com/en-US/opinions/#missing_from_js) in JavaScript +[for years](https://2022.stateofjs.com/en-US/opinions/#top_currently_missing_from_js), and there's +even a [Stage 2 proposal](https://github.com/tc39/proposal-pipeline-operator) for adding them to the +language. Sloth Pipe isn't a direct replacement for the proposed pipeline operator, but it does +offer a similar experience and many of the +[same benefits](https://github.com/tc39/proposal-pipeline-operator#why-a-pipe-operator). + +## Features + +Sloth Pipe offers a wide range of features that make it a powerful and flexible tool for working +with: + +- **Lazy Evaluation:** Computations are only performed when necessary, optimizing performance and + resource utilization. +- **Chainable API:** Enables the creation of fluent and readable code by chaining multiple + operations. +- **Error Handling:** Built-in support for error handling within the pipe. +- **Async/Await Compatibility:** Seamlessly integrate asynchronous functions into your pipes. +- **Tap Operations:** Allows side-effects without altering the pipe's main data flow. +- **Reusable pipes:** Easily reuse pipes, even after execution. +- **Extensible:** Easily extendable with custom functions and operations. +- **Type-Safe:** Written in TypeScript, with full support for type inference and type safety. +- **Lightweight:** Small and lightweight, with no external dependencies. +- **Well-Tested:** Thoroughly tested with 100% code coverage. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx new file mode 100644 index 0000000..a484046 --- /dev/null +++ b/docs/src/content/docs/index.mdx @@ -0,0 +1,18 @@ +--- +title: Welcome to Sloth Pipe +description: Get started piping functions with sloth-pipe. +template: splash +hero: + tagline: A tiny library for TypeScript and JavaScript that lets you create lazy, chainable, and reusable pipes for data transformation and processing! + image: + file: ../../assets/readme-banner.png + actions: + - text: Get started + link: /getting-started/why/ + icon: right-arrow + variant: primary + - text: Github repository + link: https://github.com/trvswgnr/sloth-pipe + icon: github +--- + diff --git a/docs/src/content/docs/reference/async-await-support.mdx b/docs/src/content/docs/reference/async-await-support.mdx new file mode 100644 index 0000000..aa4be92 --- /dev/null +++ b/docs/src/content/docs/reference/async-await-support.mdx @@ -0,0 +1,19 @@ +--- +title: Async Await Support +description: sloth-pipe supports asynchronous operations within the pipeline. +--- + +`sloth-pipe` supports asynchronous operations within the pipeline. Functions passed to `to` or `tap` +can be asynchronous, and `exec` will return a Promise if any function in the pipeline is +asynchronous. + +**Async Example**: + +```typescript +const asyncResult = await Pipe(5) + .to(async (x) => x * 2) + .to(async (x) => x + 3) + .exec(); + +console.log(asyncResult); // Outputs: 13 +``` diff --git a/docs/src/content/docs/reference/error-handling.mdx b/docs/src/content/docs/reference/error-handling.mdx new file mode 100644 index 0000000..4941807 --- /dev/null +++ b/docs/src/content/docs/reference/error-handling.mdx @@ -0,0 +1,21 @@ +--- +title: Error Handling +description: How to handle errors with sloth-pipe +--- + +`sloth-pipe` allows handling errors that may occur during function execution in the pipeline. When an +error is thrown in a `to` or `tap` method, the `catch` method is invoked if it is defined. This does +not stop the pipeline from executing, but it does allow for graceful error handling. + +**Example**: + +```typescript +const result = Pipe(5) + .to((x) => { + throw new Error("Example Error"); + }) + .catch((err) => "Error occurred") + .exec(); + +console.log(result); // Outputs: "Error occurred" +``` diff --git a/docs/src/content/docs/reference/methods.mdx b/docs/src/content/docs/reference/methods.mdx new file mode 100644 index 0000000..5bd30db --- /dev/null +++ b/docs/src/content/docs/reference/methods.mdx @@ -0,0 +1,74 @@ +--- +title: Methods +description: Exploring the methods of sloth-pipe. +--- + +## `to` + +### pipe.to(fn: Function, ...args: any[]): Pipeable + +Adds a transformation function to the pipe. + +**Parameters**: + +- `fn`: Function to be applied to the current value. +- `args`: Additional arguments to pass to the function. + +**Returns**: The modified `Pipeable` object for chaining. + +**Example**: + +```typescript +pipe.to((x) => x * 2); +``` + +## `tap` + +### pipe.tap(fn: Function, ...args: any[]): Pipeable + +Adds a side-effect function to the pipe without altering the value. + +**Parameters**: + +- `fn`: Side-effect function to be applied. +- `args`: Additional arguments to pass to the function. + +**Returns**: The modified `Pipeable` object for chaining. + +**Example**: + +```typescript +pipe.tap((x) => console.log(x)); +``` + +## `exec` + +### pipe.exec(): any + +Executes the pipe and returns the final value. + +**Returns**: The final value after applying all functions in the pipe. + +**Example**: + +```typescript +const result = pipe.exec(); +``` + +## `catch` + +### pipe.catch(fn: Function): Pipeable + +Adds an error handling function to the pipe. + +**Parameters**: + +- `fn`: Error handling function. + +**Returns**: The modified `Pipeable` object for chaining. + +**Example**: + +```typescript +pipe.catch((error) => console.error(error)); +``` diff --git a/docs/src/content/docs/reference/pipe-function.mdx b/docs/src/content/docs/reference/pipe-function.mdx new file mode 100644 index 0000000..45f6db9 --- /dev/null +++ b/docs/src/content/docs/reference/pipe-function.mdx @@ -0,0 +1,26 @@ +--- +title: Pipe Function +description: Overview of the Pipe function. +--- + +The Pipe function is the cornerstone of the Sloth Pipe library. It serves as the entry point for +creating a new pipe, setting the stage for a series of transformations or operations to be performed +on an initial value. By accepting an initial value as its parameter, it instantiates a Pipeable +object. This object then becomes the conduit through which data flows and transforms, leveraging the +library's functional programming capabilities. + +### Pipe\(initialValue: T): Pipeable\ + +Creates a new pipe with an initial value. + +**Parameters**: + +- `initialValue`: The starting value for the pipe. + +**Returns**: A `Pipeable` object representing the pipe. + +**Example**: + +```typescript +const pipe = Pipe(10); +``` diff --git a/docs/src/env.d.ts b/docs/src/env.d.ts new file mode 100644 index 0000000..acef35f --- /dev/null +++ b/docs/src/env.d.ts @@ -0,0 +1,2 @@ +/// +/// diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css new file mode 100644 index 0000000..8c09aef --- /dev/null +++ b/docs/src/styles/custom.css @@ -0,0 +1,29 @@ +/* Dark mode colors. */ +:root { + --sl-color-accent-low: #072d00; + --sl-color-accent: #247f00; + --sl-color-accent-high: #aad7a0; + --sl-color-white: #ffffff; + --sl-color-gray-1: #eaf0e8; + --sl-color-gray-2: #bdc4bb; + --sl-color-gray-3: #82907f; + --sl-color-gray-4: #4f5c4d; + --sl-color-gray-5: #303c2d; + --sl-color-gray-6: #1f2a1c; + --sl-color-black: #151a13; +} +/* Light mode colors. */ +:root[data-theme="light"] { + --sl-color-accent-low: #c0e2b8; + --sl-color-accent: #258100; + --sl-color-accent-high: #0d3e00; + --sl-color-white: #151a13; + --sl-color-gray-1: #1f2a1c; + --sl-color-gray-2: #303c2d; + --sl-color-gray-3: #4f5c4d; + --sl-color-gray-4: #82907f; + --sl-color-gray-5: #bdc4bb; + --sl-color-gray-6: #eaf0e8; + --sl-color-gray-7: #f4f7f3; + --sl-color-black: #ffffff; +} diff --git a/docs/tsconfig.json b/docs/tsconfig.json new file mode 100644 index 0000000..77da9dd --- /dev/null +++ b/docs/tsconfig.json @@ -0,0 +1,3 @@ +{ + "extends": "astro/tsconfigs/strict" +} \ No newline at end of file diff --git a/package.json b/package.json index 9a2a61e..73a195a 100644 --- a/package.json +++ b/package.json @@ -1,31 +1,14 @@ { - "name": "sloth-pipe", - "description": "A pipe utility that lazily evaluates only when needed, and only once.", + "name": "sloth-pipe-root", + "private": true, + "description": "", "version": "0.0.6", - "type": "module", - "main": "dist/index.js", - "exports": { - ".": { - "import": "./dist/index.js", - "require": "./dist/index.cjs" - }, - "./fifo-queue": { - "import": "./dist/fifo-queue.js", - "require": "./dist/fifo-queue.cjs" - } - }, "scripts": { - "build": "tsup", - "lint": "tsc", - "bench": "bun ./pipe.bench.ts" - }, - "devDependencies": { - "bun-types": "1.0.20", - "mitata": "^0.1.6", - "tsup": "^8.0.1", - "typescript": "5.3.3" + "docs": "cd docs && bun dev" }, - "files": [ - "dist" + "workspaces": [ + "benchmarks", + "docs", + "src" ] } diff --git a/api-docs.md b/src/api-docs.md similarity index 100% rename from api-docs.md rename to src/api-docs.md diff --git a/src/bun.lockb b/src/bun.lockb new file mode 100755 index 0000000..70ec2af Binary files /dev/null and b/src/bun.lockb differ diff --git a/fifo-queue.test.ts b/src/fifo-queue.test.ts similarity index 100% rename from fifo-queue.test.ts rename to src/fifo-queue.test.ts diff --git a/fifo-queue.ts b/src/fifo-queue.ts similarity index 100% rename from fifo-queue.ts rename to src/fifo-queue.ts diff --git a/src/package.json b/src/package.json new file mode 100644 index 0000000..9a2a61e --- /dev/null +++ b/src/package.json @@ -0,0 +1,31 @@ +{ + "name": "sloth-pipe", + "description": "A pipe utility that lazily evaluates only when needed, and only once.", + "version": "0.0.6", + "type": "module", + "main": "dist/index.js", + "exports": { + ".": { + "import": "./dist/index.js", + "require": "./dist/index.cjs" + }, + "./fifo-queue": { + "import": "./dist/fifo-queue.js", + "require": "./dist/fifo-queue.cjs" + } + }, + "scripts": { + "build": "tsup", + "lint": "tsc", + "bench": "bun ./pipe.bench.ts" + }, + "devDependencies": { + "bun-types": "1.0.20", + "mitata": "^0.1.6", + "tsup": "^8.0.1", + "typescript": "5.3.3" + }, + "files": [ + "dist" + ] +} diff --git a/pipe.bench.ts b/src/pipe.bench.ts similarity index 100% rename from pipe.bench.ts rename to src/pipe.bench.ts diff --git a/pipe.test.ts b/src/pipe.test.ts similarity index 100% rename from pipe.test.ts rename to src/pipe.test.ts diff --git a/pipe.ts b/src/pipe.ts similarity index 100% rename from pipe.ts rename to src/pipe.ts diff --git a/tsup.config.ts b/src/tsup.config.ts similarity index 100% rename from tsup.config.ts rename to src/tsup.config.ts