`file`

Function, in @jr2/orchestrator/src/http-effect.ts. It is an export of @jr2/orchestrator, on the Authoring surface page, in Effects.

function file<S extends z.ZodType | undefined = undefined>(path: FromInput<S, string>, options: {
  slot?: string;
  segments?: FromInput<S, readonly string[]>;
  contentType?: string;
} = {}): FileBody<S>

Make a Worktree file the body of an http Effect: body: file("dist/report.pdf"). The Effect then runs in the Sandbox Effector of the Workspace whose body invokes it. That Effector opens the file in the Worktree and sends it. In a Workspace with no Repo Slot, the path is relative to /work, the folder that its steps share. Use it with PUT, POST or PATCH. path and segments can be functions of the input of the Effect.

Some paths and files give the output refused, and then nothing is sent. The path has a symlink in it, has .., or is absolute. Or the file is a FIFO, a directory, or a file with more than one link.

It refuses, when you call it:

a path that is not a string or a function: file(path): the path is a string, or a function of the Effect's input that returns one

And when http takes the definition:

a method other than PUT, POST and PATCH: http({ method: "<method>", body: file(...) }): a file body is sent with PUT, POST, PATCH (ADR-0068)
a request beside it: http({ body: file(...), request }): with a file body the run's part is file()'s — its path, from the input if it must be, and its `segments` — so write no `request` (ADR-0068)
a content-type header and contentType: http({ headers, body: file(path, { contentType }) }): "content-type" is set by file()'s contentType — write one of them (ADR-0067)

And at jr2 up, an Effect that no workspace() invokes: workflow "<workflow>": the http Effect "<slot>" sends a Worktree file as its body, and no workspace() invokes it — outside a Workspace there is no Worktree to read; invoke it from a workspace()'s body, or send a json or text body (ADR-0068).

Parameters

path (FromInput): The file, relative to the Worktree of the Repo Slot, or to /work in a Workspace with no Repo Slot: a string, or a function of the input of the Effect that gives one.
options: Optional. Each field says what it does.
- slot (optional): string
  The Repo Slot whose Worktree holds the file. Write it only when the Workspace has more than one.
- segments (optional): FromInput<S, readonly string[]>
  Path segments that jr2 adds to the end of the url, as path does in request for a json or text body. A list of strings, or a function of the input of the Effect that gives one.
- contentType (optional): string
  The content type of the body. Default application/octet-stream. Do not write it beside a content-type header.

Returns: The body of an http Effect.

Example

import {
  bearer,
  command,
  fail,
  file,
  http,
  jr2Setup,
  secret,
  workspace,
  type Workspaced,
} from "@jr2/orchestrator";

type Input = Workspaced<{}, "app">;

const body = jr2Setup({
  types: {} as { context: Input; input: Input },
  actors: {
    build: command(["npm", "run", "report"]),
    upload: http({
      method: "PUT",
      url: "https://files.example.com/reports",
      auth: bearer(secret("files")),
      body: file("dist/report.pdf", {
        segments: ["report.pdf"],
        contentType: "application/pdf",
      }),
    }),
    fail: fail(),
  },
}).createMachine({
  id: "report",
  context: ({ input }) => input,
  on: { "workspace.lost": ".lost" },
  initial: "building",
  states: {
    building: { invoke: { src: "build", onDone: "uploading" } },
    uploading: { invoke: { src: "upload", onDone: "done" } },
    done: { type: "final" },
    lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
  },
});

export const machine = workspace(body, {
  repos: { app: { url: "https://github.com/you/app.git" } },
  spec: () => ({ branch: "report" }),
});

See also

file ​

`file`