effect-github-actions-layer

An effect layer to interact with github actions toolkit.

⚡ Quick start

🔶 Install

npm i effect-github-actions-layer
# or
pnpm i effect-github-actions-layer
# or
bun i effect-github-actions-layer

🔶 Use the layer

You can use the GithubActionsLayer object:

import { Effect, Layer, pipe } from 'effect';

import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.exec('git diff', ['--quiet', './*'], {
    ignoreReturnCode: true,
  }),
  Effect.provide(GithubActionsLayerLive)
);

Or you can use the layer tag directly:

import {
  GithubActions,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const { exec } = yield* GithubActions;

    const result = yield* exec('git diff', ['--quiet', './*'], {
      ignoreReturnCode: true,
    });
  }),
  Effect.provide(GithubActionsLayerLive)
);

⚡ API

🔶 @actions/core - inputs/outputs

| function | description | | ------------------------------------------ | ------------------------------------------------------------------------- | | exportVariable | Export a variable for next steps environement | | setOutput | Make the action return a specific output, available for use in next steps | | getBooleanInput | Get a boolean input as per yaml spec | | getInput | Create a string input | | getMultilineInput | Create a multiline string input |

🧿 exportVariable

// Type
type ExportVariableEffect = (
  name: string,
  value: unknown
) => Effect.Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.exportVariable('myVar', 1),
  Effect.provide(GithubActionsLayerLive)
);

🧿 setOutput

// Type
type SetOutputEffect = (
  name: string,
  value: unknown
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.setOutput('success', true),
  Effect.provide(GithubActionsLayerLive)
);

🧿 getBooleanInput

type GetBooleanInputEffect = (
  name: string,
  options?: InputOptions
) => Effect<boolean, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const myBoolean = yield* GithubActionsLayer.getBooleanInput('my-var');
  }),
  Effect.provide(GithubActionsLayerLive)
);

🧿 getInput

// Type
type GetInputEffect = (
  name: string,
  options?: InputOptions
) => Effect<string, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const myString = yield* GithubActionsLayer.getInput('my-var');
  }),
  Effect.provide(GithubActionsLayerLive)
);

🧿 getMultilineInput

// Type
type GetMultilineInputEffect = (
  name: string,
  options?: InputOptions
) => Effect<string[], GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const myStringArray = yield* GithubActionsLayer.getMultilineInput('my-var');
  }),
  Effect.provide(GithubActionsLayerLive)
);

🔶 @actions/core - exit codes

| function | description | | -------------------------- | --------------------------------------------- | | setFailed | Report an action failure and end the workflow |

🧿 setFailed

// Type
type SetFailedEffect = (
  message: string
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.setFailed('Oh no!'),
  Effect.provide(GithubActionsLayerLive)
);

🔶 @actions/core - action state

| function | description | | -------------------------- | ---------------------------------------------- | | saveState | Save state to be used within an action wrapper | | getState | Get wrapper state |

🧿 saveState

// Type
type SaveStateEffect = (
  name: string,
  value: unknown
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.saveState('myVar', 1),
  Effect.provide(GithubActionsLayerLive)
);

🧿 getState

// Type
type GetStateEffect = (
  name: string
) => Effect<string, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const myString = yield* GithubActionsLayer.getState('myVar');
  }),
  Effect.provide(GithubActionsLayerLive)
);

🔶 @actions/core - logging

| function | description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | isDebug | Check whether run is in debug mode | | debug | Create a debug level log (not visible by default) | | info | Create an info level log | | warning | Create a warning level log | | error | Create an error level log |

🧿 isDebug

// Type
type IsDebugEffect = () => Effect<
  boolean,
  GithubActionsLayerError,
  GithubActionsInterface
>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const debug = yield* GithubActionsLayer.isDebug();
  }),
  Effect.provide(GithubActionsLayerLive)
);

🧿 debug

// Type
type DebugEffect = (
  message: string
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.debug('Blah blah'),
  Effect.provide(GithubActionsLayerLive)
);

🧿 info

// Type
type InfoEffect = (
  message: string
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.info('Blah blah'),
  Effect.provide(GithubActionsLayerLive)
);

🧿 warning

// Type
type WarningEffect = (
  message: string,
  properties?: AnnotationProperties
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.warning('Blah blah'),
  Effect.provide(GithubActionsLayerLive)
);

🧿 error

// Type
type ErrorEffect = (
  message: string,
  properties?: AnnotationProperties
) => Effect<void, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  GithubActionsLayer.error('Blah blah'),
  Effect.provide(GithubActionsLayerLive)
);

🔶 @actions/exec

| function | description | | ---------------- | ------------------------------------ | | exec | cross-platform execution of commands |

🧿 exec

// type
type ExecEffect = (
  commandLine: string,
  args?: string[],
  options?: ExecOptions
) => Effect<number, GithubActionsLayerError, GithubActionsInterface>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const result = yield* GithubActionsLayer.exec('git reset', ['--hard']);
  }),
  Effect.provide(GithubActionsLayerLive)
);

🔶 @actions/github

| function | description | | ---------------------------- | ------------------------------ | | getContext | Get the current action context |

🧿 getContext

// Type
import type { GithubContext } from 'effect-github-actions-layer';

type GetContextEffect = () => Effect<
  GithubContext,
  GithubActionsLayerError,
  GithubActionsInterface
>;

// Usage
import { Effect, Layer, pipe } from 'effect';
import {
  GithubActionsLayer,
  GithubActionsLayerLive,
} from 'effect-github-actions-layer';

const task = pipe(
  Effect.gen(function* () {
    const githubContext = yield* GithubActionsLayer.getContext();
  }),
  Effect.provide(GithubActionsLayerLive)
);