@rc312/effect-snowflake 0.0.0-stage → 0.2.0

package/examples/composition.ts

@@ -0,0 +1,24 @@
+import * as Snowflake from "@rc312/effect-snowflake";
+import { tableFromArrays } from "apache-arrow";
+import { Effect, flow, Schema } from "effect";
+
+import { runProgram } from "./run.ts";
+
+// Build a reusable workflow, add decoding, then wrap the whole Effect in a
+// transaction. No connection or callback needs to be threaded through its steps.
+const lookup = flow(
+  (id: bigint) =>
+    Snowflake.query(
+      'select ?::number(38, 0)::varchar as "id"',
+      tableFromArrays({ id: new BigInt64Array([id]) })
+    ),
+  Effect.flatMap((table) =>
+    Schema.decodeUnknownEffect(Schema.Struct({ id: Schema.String }))(
+      table.get(0)?.toJSON()
+    )
+  ),
+  Effect.map((row) => row.id),
+  Snowflake.withTransaction
+);
+
+await runProgram(lookup(9_007_199_254_740_993n));

package/examples/options.ts

@@ -0,0 +1,80 @@
+import type { SnowflakeOptions } from "@rc312/effect-snowflake";
+import { Config, Effect, Option, Redacted } from "effect";
+
+/** Shared environment recipe for the runnable examples and live E2E suite. */
+export const optionsFromEnv = Effect.fn("Snowflake.Example.options")(
+  function* loadOptions() {
+    const settings = yield* Config.all({
+      account: Config.NonEmptyString("SNOWFLAKE_ACCOUNT"),
+      authenticator: Config.Literals(
+        [
+          "auth_snowflake",
+          "auth_jwt",
+          "auth_oauth",
+          "auth_ext_browser",
+          "auth_okta",
+          "auth_mfa",
+          "auth_pat",
+          "auth_wif",
+        ],
+        "SNOWFLAKE_AUTHENTICATOR"
+      ).pipe(Config.withDefault("auth_jwt")),
+      database: Config.NonEmptyString("SNOWFLAKE_DATABASE"),
+      driver: Config.NonEmptyString("SNOWFLAKE_ADBC_DRIVER").pipe(
+        Config.withDefault("snowflake")
+      ),
+      schema: Config.NonEmptyString("SNOWFLAKE_SCHEMA"),
+      username: Config.NonEmptyString("SNOWFLAKE_USERNAME"),
+      warehouse: Config.NonEmptyString("SNOWFLAKE_WAREHOUSE"),
+    });
+
+    const optional = yield* Config.all({
+      password: Config.option(Config.Redacted("SNOWFLAKE_PASSWORD")),
+      privateKey: Config.option(Config.Redacted("SNOWFLAKE_PRIVATE_KEY")),
+      privateKeyPass: Config.option(
+        Config.Redacted("SNOWFLAKE_PRIVATE_KEY_PASS")
+      ),
+      privateKeyPath: Config.option(
+        Config.NonEmptyString("SNOWFLAKE_PRIVATE_KEY_PATH")
+      ),
+      role: Config.option(Config.NonEmptyString("SNOWFLAKE_ROLE")),
+      token: Config.option(Config.Redacted("SNOWFLAKE_TOKEN")),
+    });
+
+    const options: SnowflakeOptions = {
+      ...settings,
+      databaseOptions: {
+        "adbc.snowflake.sql.client_option.client_timeout": Redacted.make("30s"),
+        "adbc.snowflake.sql.client_option.login_timeout": Redacted.make("30s"),
+        "adbc.snowflake.sql.client_option.request_timeout":
+          Redacted.make("60s"),
+      },
+    };
+
+    if (Option.isSome(optional.password)) {
+      Object.assign(options, { password: optional.password.value });
+    }
+
+    if (Option.isSome(optional.privateKey)) {
+      Object.assign(options, { privateKey: optional.privateKey.value });
+    }
+
+    if (Option.isSome(optional.privateKeyPass)) {
+      Object.assign(options, { privateKeyPass: optional.privateKeyPass.value });
+    }
+
+    if (Option.isSome(optional.privateKeyPath)) {
+      Object.assign(options, { privateKeyPath: optional.privateKeyPath.value });
+    }
+
+    if (Option.isSome(optional.role)) {
+      Object.assign(options, { role: optional.role.value });
+    }
+
+    if (Option.isSome(optional.token)) {
+      Object.assign(options, { token: optional.token.value });
+    }
+
+    return options;
+  }
+);

package/examples/query.ts

@@ -0,0 +1,4 @@
+import { runExample } from "./run.ts";
+import { queryExample } from "./scenarios.ts";
+
+await runExample(queryExample);

package/examples/run.ts

@@ -0,0 +1,30 @@
+import { layerFrom, makeWithDriver, Snowflake } from "@rc312/effect-snowflake";
+import type { SnowflakeClient } from "@rc312/effect-snowflake";
+import { layer as nativeDriver } from "@rc312/effect-snowflake/adbc-driver";
+import { Effect, Layer, pipe } from "effect";
+
+import { optionsFromEnv } from "./options.ts";
+
+// The application chooses configuration and the native loader once. The Layer
+// owns the connection until the entire program, including finalizers, finishes.
+const live = layerFrom(
+  optionsFromEnv().pipe(Effect.flatMap(makeWithDriver))
+).pipe(Layer.provide(nativeDriver));
+
+/** Runtime boundary for service-based example programs. */
+export const runProgram = async <A, E>(
+  program: Effect.Effect<A, E, Snowflake>
+) => {
+  try {
+    const result = await Effect.runPromise(program.pipe(Effect.provide(live)));
+    console.dir(result, { depth: null });
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+};
+
+/** The scoped client factory API composes with the same application layer. */
+export const runExample = <A, E>(
+  use: (client: SnowflakeClient) => Effect.Effect<A, E>
+) => runProgram(pipe(Snowflake, Effect.flatMap(use)));

package/examples/scenarios.ts

@@ -0,0 +1,114 @@
+import type { SnowflakeClient } from "@rc312/effect-snowflake";
+import {
+  Bool,
+  Int64,
+  Table,
+  tableFromArrays,
+  Utf8,
+  vectorFromArray,
+} from "apache-arrow";
+import { Data, Effect, Schema, Stream } from "effect";
+
+const queryRow = Schema.Struct({
+  enabled: Schema.Boolean,
+  id: Schema.String,
+  label: Schema.String,
+  optional: Schema.Null,
+});
+
+/** Bind Arrow int64, text, boolean, and a typed null, then decode a result. */
+export const queryExample = Effect.fn("Snowflake.Example.query")(
+  function* query(client: SnowflakeClient) {
+    const parameters = new Table({
+      enabled: vectorFromArray([true], new Bool()),
+      id: vectorFromArray([9_007_199_254_740_993n], new Int64()),
+      label: vectorFromArray(["hello ? -- Snowflake"], new Utf8()),
+      optional: vectorFromArray([null], new Utf8()),
+    });
+
+    const result = yield* client.query(
+      'select ?::boolean as "enabled", ?::number(38, 0)::varchar as "id", ?::varchar as "label", ?::varchar as "optional"',
+      parameters
+    );
+
+    return yield* Schema.decodeUnknownEffect(queryRow)(result.get(0)?.toJSON());
+  }
+);
+
+/** Count a complete stream, stop another after one batch, then reuse its client. */
+export const streamExample = Effect.fn("Snowflake.Example.stream")(
+  function* stream(client: SnowflakeClient) {
+    const totalRows = yield* client
+      .stream("select seq4() from table(generator(rowcount => 1000))")
+      .pipe(
+        Stream.runFold(
+          () => 0,
+          (count, batch) => count + batch.numRows
+        )
+      );
+
+    const firstBatchRows = yield* client
+      .stream("select seq4() from table(generator(rowcount => 100000))")
+      .pipe(
+        Stream.filter((batch) => batch.numRows > 0),
+        Stream.take(1),
+        Stream.runFold(
+          () => 0,
+          (count, batch) => count + batch.numRows
+        )
+      );
+
+    const next = yield* client.query("select 'ok' as \"status\"");
+
+    const { status } = yield* Schema.decodeUnknownEffect(
+      Schema.Struct({ status: Schema.Literal("ok") })
+    )(next.get(0)?.toJSON());
+
+    return { firstBatchRows, status, totalRows };
+  }
+);
+
+class RollbackExample extends Data.TaggedError("RollbackExample") {}
+
+/** Create a session-temporary table before DML transactions and always drop it. */
+export const transactionExample = Effect.fn("Snowflake.Example.transaction")(
+  function* transactions(client: SnowflakeClient) {
+    return yield* Effect.acquireUseRelease(
+      client.execute(
+        "create temporary table EFFECT_SNOWFLAKE_EXAMPLE (ID number(38, 0))"
+      ),
+      () =>
+        Effect.gen(function* commitAndRollback() {
+          yield* client
+            .execute(
+              "insert into EFFECT_SNOWFLAKE_EXAMPLE values (?)",
+              tableFromArrays({ id: [1] })
+            )
+            .pipe(client.withTransaction);
+          yield* client
+            .execute(
+              "insert into EFFECT_SNOWFLAKE_EXAMPLE values (?)",
+              tableFromArrays({ id: [2] })
+            )
+            .pipe(
+              Effect.andThen(Effect.fail(new RollbackExample())),
+              client.withTransaction,
+              Effect.catchTag("RollbackExample", () => Effect.void)
+            );
+
+          const rows = yield* client.query(
+            'select ID::varchar as "id" from EFFECT_SNOWFLAKE_EXAMPLE order by ID'
+          );
+
+          return yield* Schema.decodeEffect(
+            Schema.Array(Schema.Struct({ id: Schema.String }))
+          )(Array.from(rows, (row) => row.toJSON()));
+        }),
+      // A failed drop must remain visible even when the transaction already failed.
+      () =>
+        client
+          .execute("drop table if exists EFFECT_SNOWFLAKE_EXAMPLE")
+          .pipe(Effect.orDie)
+    );
+  }
+);

package/examples/stream.ts

@@ -0,0 +1,4 @@
+import { runExample } from "./run.ts";
+import { streamExample } from "./scenarios.ts";
+
+await runExample(streamExample);

package/examples/transaction.ts

@@ -0,0 +1,4 @@
+import { runExample } from "./run.ts";
+import { transactionExample } from "./scenarios.ts";
+
+await runExample(transactionExample);

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@rc312/effect-snowflake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Scoped Effect 4 Snowflake client with Apache Arrow ADBC queries, streams, and transactions.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RyanCallahan312/effect-extensions.git",
+    "directory": "packages/effect-snowflake"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "examples"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json",
+    "./adbc-driver": "./dist/adbc-driver.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "dev": "tsc -b tsconfig.json --watch",
+    "typecheck": "bun run build && tsc --noEmit -p tsconfig.json --tsBuildInfoFile .cache/typecheck.tsbuildinfo && tsc -p tsconfig.test.json && tsc -p tsconfig.examples.json --noEmit",
+    "test": "bun run build && vitest run && bun run test:cli",
+    "prepack": "bun run build",
+    "test:coverage": "bun run build && vitest run --coverage",
+    "build:examples": "bun run build && tsc -p tsconfig.examples.json",
+    "example:query": "bun run build:examples && node --env-file-if-exists=.env .cache/examples/examples/query.js",
+    "example:stream": "bun run build:examples && node --env-file-if-exists=.env .cache/examples/examples/stream.js",
+    "example:transaction": "bun run build:examples && node --env-file-if-exists=.env .cache/examples/examples/transaction.js",
+    "example:check": "bun run build:examples && node --env-file-if-exists=.env .cache/examples/examples/check.js",
+    "test:e2e": "bun run build:examples && node --env-file-if-exists=.env --test .cache/examples/e2e/*.test.js",
+    "test:cli": "bun run build:examples && node --test test/*.test.mjs",
+    "example:composition": "bun run build:examples && node --env-file-if-exists=.env .cache/examples/examples/composition.js"
+  },
+  "dependencies": {
+    "@apache-arrow/adbc-driver-manager": "~0.24.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^4.1.2",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "5.0.4",
+    "vitest": "^5.0.4"
+  },
+  "peerDependencies": {
+    "apache-arrow": "^21.1.0",
+    "effect": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/adbc-driver.ts

@@ -0,0 +1,83 @@
+import type {
+  AdbcConnection,
+  AdbcStatement,
+  AdbcDatabase,
+  ConnectOptions,
+} from "@apache-arrow/adbc-driver-manager";
+import { Context, Effect, Layer } from "effect";
+
+import { failure } from "./snowflake-error.ts";
+import type { SnowflakeError } from "./snowflake-error.ts";
+
+/**
+ * Minimal native database resource owned by a scoped client.
+ * Implementations must await acquisition/cleanup rather than detach native work.
+ * @since 0.1.0
+ */
+export interface Database {
+  /** Open a connection; the adapter owns it after this Promise resolves. */
+  readonly connect: () => Promise<Connection>;
+  /** Release database resources after all owned connections have closed. */
+  readonly close: AdbcDatabase["close"];
+}
+
+/**
+ * Native statement operations used by the adapter. Each query receives a fresh
+ * instance. A returned reader is released before `close` is invoked.
+ * @since 0.1.0
+ */
+export type Statement = Pick<
+  AdbcStatement,
+  "setSqlQuery" | "bind" | "executeQuery" | "executeUpdate" | "close"
+>;
+
+/**
+ * Native connection boundary. Methods are called under an exclusive permit;
+ * `createStatement` must return a fresh statement for each call.
+ * @since 0.1.0
+ */
+export type Connection = Pick<
+  AdbcConnection,
+  "setAutoCommit" | "commit" | "rollback" | "close"
+> & { readonly createStatement: () => Promise<Statement> };
+
+/**
+ * Loader service required by `makeWithDriver` for alternate native loading or
+ * controlled tests. `open` must map native failures to sanitized Snowflake errors.
+ * Use {@link layer} for the standard Apache Arrow implementation.
+ * @since 0.1.0
+ */
+export class AdbcDriver extends Context.Service<
+  AdbcDriver,
+  {
+    /** Construct the database; the client owns and closes a successful result. */
+    readonly open: (
+      options: ConnectOptions
+    ) => Effect.Effect<Database, SnowflakeError>;
+  }
+>()("@rc312/effect-snowflake/AdbcDriver") {}
+
+/**
+ * Standard loader layer. Importing it does not load the native addon; `open` does.
+ * Addon import failures use operation `driver.load`; database construction failures
+ * use `database.open`. Raw native messages and causes are excluded from both.
+ * @since 0.1.0
+ */
+export const layer = Layer.succeed(
+  AdbcDriver,
+  AdbcDriver.of({
+    open: Effect.fn("Snowflake.AdbcDriver.open")(
+      function* openDatabase(options) {
+        const { AdbcDatabase } = yield* Effect.tryPromise({
+          catch: failure("driver.load"),
+          try: () => import("@apache-arrow/adbc-driver-manager"),
+        });
+
+        return yield* Effect.try({
+          catch: failure("database.open"),
+          try: () => new AdbcDatabase(options),
+        });
+      }
+    ),
+  })
+);

package/src/index.ts

@@ -0,0 +1,151 @@
+import type { RecordBatch, Table } from "apache-arrow";
+import { Config, Context, Effect, flow, pipe, Layer, Stream } from "effect";
+
+import { layer as driverLayer } from "./adbc-driver.ts";
+import * as Client from "./internal/client.ts";
+import * as Connection from "./internal/connection.ts";
+import { acquireOwner } from "./internal/lifecycle.ts";
+import type {
+  SnowflakeClient,
+  SnowflakeOptions,
+  SnowflakeSession,
+} from "./models.ts";
+import type { SnowflakeError } from "./snowflake-error.ts";
+
+export type {
+  SnowflakeClient,
+  SnowflakeOptions,
+  SnowflakeSession,
+} from "./models.ts";
+
+export { SnowflakeError } from "./snowflake-error.ts";
+
+/**
+ * Injected client service. Its layer owns one connection and captures its driver.
+ * Reuse the same layer value when repositories should share that connection.
+ * @since 0.1.0
+ */
+export class Snowflake extends Context.Service<
+  Snowflake,
+  {
+    readonly query: SnowflakeSession["query"];
+    readonly execute: SnowflakeSession["execute"];
+    readonly stream: SnowflakeSession["stream"];
+    readonly transaction: SnowflakeClient["transaction"];
+    readonly withTransaction: SnowflakeClient["withTransaction"];
+  }
+>()("@rc312/effect-snowflake/Snowflake") {}
+
+/**
+ * Acquire a connected client through an injected `AdbcDriver` service.
+ *
+ * @param options Native Snowflake settings; construction performs no I/O.
+ * @returns An Effect requiring `Scope` and `AdbcDriver`. The scope joins active
+ * operations before closing connection and database, even under parallel teardown.
+ * Failed acquisition immediately releases its partial resources and child scope.
+ *
+ * Custom loaders must normalize native errors to sanitized `SnowflakeError`s.
+ * Native calls have no cancellation API: configure driver network/login timeouts
+ * to bound shutdown. Prefer {@link make} when using the standard native manager.
+ * @since 0.1.0
+ */
+export const makeWithDriver = Effect.fn("Snowflake.make")(
+  flow(Connection.make, Effect.flatMap(Client.make), acquireOwner)
+);
+
+/**
+ * Acquire a server-only Snowflake connection through the Apache Arrow ADBC manager.
+ *
+ * @param options Connection settings. The Snowflake shared-library driver must be
+ * installed separately; `driver` defaults to `snowflake`.
+ * @returns A lazy Effect requiring `Scope`. Its scope owns connection and database.
+ * Driver loading and connection errors are sanitized `SnowflakeError`s. Native
+ * calls settle before interruption releases resources; queries are never retried.
+ *
+ * @example
+ * ```ts
+ * import { make } from "@rc312/effect-snowflake";
+ * import { Config, Effect } from "effect";
+ *
+ * const program = Effect.scoped(Effect.gen(function* () {
+ *   const db = yield* make({
+ *     account: yield* Config.String("SNOWFLAKE_ACCOUNT"),
+ *     username: yield* Config.String("SNOWFLAKE_USERNAME"),
+ *     password: yield* Config.Redacted("SNOWFLAKE_PASSWORD"),
+ *   });
+ *   return yield* db.query("select current_version() as VERSION");
+ * }));
+ * ```
+ * @since 0.1.0
+ */
+export const make = Effect.fn("Snowflake.makeDefault")(
+  (options: SnowflakeOptions) =>
+    makeWithDriver(options).pipe(Effect.provide(driverLayer))
+);
+
+/**
+ * Provide the service from an existing acquisition Effect, retaining its errors
+ * and dependencies. The Layer owns any Scope required by the acquisition.
+ * Useful for application-owned configuration, instrumentation, and test clients.
+ * @since 0.1.0
+ */
+export const layerFrom = <E, R>(
+  acquire: Effect.Effect<SnowflakeClient, E, R>
+) => Layer.effect(Snowflake, acquire);
+
+/**
+ * Provide a scoped Snowflake service using an injected AdbcDriver.
+ * Compose with `Layer.provide(AdbcDriver.layer)` at the application boundary.
+ * @since 0.1.0
+ */
+export const layer = (options: SnowflakeOptions) =>
+  layerFrom(makeWithDriver(options));
+
+/**
+ * Read Config values when the layer is built, then acquire its scoped client.
+ * Accepts one Config or a record of Config fields; ConfigProvider stays caller-owned.
+ * Requires the same explicit AdbcDriver dependency as {@link layer}.
+ * @since 0.1.0
+ */
+export const layerConfig = (options: Config.Wrap<SnowflakeOptions>) =>
+  Layer.unwrap(Config.unwrap(options).pipe(Effect.map(layer)));
+
+/** Query the injected client, or the active transaction's scoped session. @since 0.1.0 */
+export const query = (sql: string, parameters?: Table) =>
+  pipe(
+    Snowflake,
+    Effect.flatMap((client) => client.query(sql, parameters))
+  );
+
+/** Execute DML/DDL on the injected client. @since 0.1.0 */
+export const execute = (sql: string, parameters?: Table) =>
+  pipe(
+    Snowflake,
+    Effect.flatMap((client) => client.execute(sql, parameters))
+  );
+
+/** Lazily stream batches from the injected client; the consumer owns its permit. @since 0.1.0 */
+export const stream = (
+  sql: string,
+  parameters?: Table
+): Stream.Stream<RecordBatch, SnowflakeError, Snowflake> =>
+  Stream.unwrap(
+    pipe(
+      Snowflake,
+      Effect.map((client) => client.stream(sql, parameters))
+    )
+  );
+
+/**
+ * Run an Effect in a transaction using the injected client. Pipe it around a
+ * composed workflow; accessors and `yield* Snowflake` both resolve its session.
+ * Nested transactions fail with operation `transaction.nested` (Snowflake has no
+ * savepoints). Callback errors, defects, service requirements, and interruption
+ * are preserved by the underlying transaction implementation.
+ * @since 0.1.0
+ */
+export const withTransaction = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+  pipe(
+    Snowflake,
+    Effect.flatMap((client) => client.withTransaction(self))
+  );

package/src/internal/client.ts

@@ -0,0 +1,69 @@
+import { Context, Effect, Option, Semaphore, Stream } from "effect";
+
+import type { SnowflakeClient, SnowflakeSession } from "../models.ts";
+import { failure } from "../snowflake-error.ts";
+import type { Connection } from "./connection.ts";
+import * as Session from "./session.ts";
+import * as Transaction from "./transaction.ts";
+
+// Each client needs its own fiber-local session key, as in Effect SqlClient.
+// A transaction on one client must never route another client's queries.
+let nextClientId = 0;
+
+/** Capture the connection; client methods have no dependency requirements. */
+export const make = Effect.fnUntraced(function* makeClient(
+  connection: Connection
+): Effect.fn.Return<SnowflakeClient> {
+  const lock = yield* Semaphore.make(1);
+
+  const direct = Session.make(
+    connection,
+    connection.owner,
+    lock,
+    connection.isOpen
+  );
+
+  const transactionSession = Context.Service<SnowflakeSession>(
+    `@rc312/effect-snowflake/Transaction/${(nextClientId += 1)}`
+  );
+
+  const currentSession = Effect.serviceOption(transactionSession).pipe(
+    Effect.map(Option.getOrElse(() => direct))
+  );
+
+  const runTransaction = Transaction.make(connection, lock);
+
+  const transaction: SnowflakeClient["transaction"] = <A, E, R>(
+    use: (session: SnowflakeSession) => Effect.Effect<A, E, R>
+  ) =>
+    Effect.serviceOption(transactionSession).pipe(
+      Effect.flatMap((current) => {
+        if (Option.isSome(current)) {
+          return Effect.fail(failure("transaction.nested")());
+        }
+
+        return runTransaction((session) =>
+          Effect.provideService(use(session), transactionSession, session)
+        );
+      })
+    );
+
+  return {
+    execute: (sql, parameters) =>
+      currentSession.pipe(
+        Effect.flatMap((session) => session.execute(sql, parameters))
+      ),
+    query: (sql, parameters) =>
+      currentSession.pipe(
+        Effect.flatMap((session) => session.query(sql, parameters))
+      ),
+    stream: (sql, parameters) =>
+      Stream.unwrap(
+        currentSession.pipe(
+          Effect.map((session) => session.stream(sql, parameters))
+        )
+      ),
+    transaction,
+    withTransaction: (self) => transaction(() => self),
+  };
+});