@flipt-io/flipt-client-js 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flipt Software Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# Flipt Client JS
+
+[![flipt-client-js](https://img.shields.io/npm/v/@flipt-io/flipt-client-js?label=%40flipt-io%2Fflipt-client-js)](https://www.npmjs.com/package/@flipt-io/flipt-client-js)
+
+The `flipt-client-js` library contains the JavaScript/TypeScript client for Flipt [client-side evaluation](https://www.flipt.io/docs/integration/client) in web and Node.js environments. It supports:
+
+- Node.js
+- Browsers
+- Edge Functions (Vercel Edge, Cloudflare Workers, etc.)
+- Web Workers
+
+## Installation
+
+```bash
+npm install @flipt-io/flipt-client-js
+```
+
+## Usage
+
+```typescript
+import { FliptClient } from '@flipt-io/flipt-client-js';
+
+const client = await FliptClient.init('default', {
+  url: 'http://localhost:8080',
+  authentication: {
+    clientToken: 'secret'
+  }
+});
+
+const variant = client.evaluateVariant('flag1', 'someentity', {
+  fizz: 'buzz'
+});
+
+console.log(variant);
+```
+
+### Edge Function Usage (e.g., Vercel Edge)
+
+```typescript
+import { FliptClient } from '@flipt-io/flipt-client-js';
+
+export const config = {
+  runtime: 'edge'
+};
+
+export default async function middleware(req) {
+  const client = await FliptClient.init('default', {
+    url: process.env.FLIPT_URL,
+    authentication: {
+      clientToken: process.env.FLIPT_AUTH_TOKEN
+    }
+  });
+
+  const result = client.evaluateBoolean('my-flag', 'user-123', {
+    country: 'US'
+  });
+
+  if (result.enabled) {
+    return new Response('Feature enabled!');
+  }
+
+  return new Response('Feature disabled');
+}
+```
+
+### Initialization Arguments
+
+The `FliptClient` constructor accepts two optional arguments:
+
+- `namespace`: The namespace to fetch flag state from. If not provided, the client will default to the `default` namespace.
+- `options`: An instance of the `ClientOptions` type that supports several options for the client. The structure is:
+  - `url`: The URL of the upstream Flipt instance. If not provided, the client will default to `http://localhost:8080`.
+  - `updateInterval`: **Node.js Only** The interval (in seconds) in which to fetch new flag state. If not provided, the client will default to 120 seconds.
+  - `authentication`: The authentication strategy to use when communicating with the upstream Flipt instance. If not provided, the client will default to no authentication. See the [Authentication](#authentication) section for more information.
+  - `reference`: The [reference](https://docs.flipt.io/guides/user/using-references) to use when fetching flag state. If not provided, reference will not be used.
+  - `fetcher`: An implementation of a [fetcher](https://github.com/flipt-io/flipt-client-sdks/blob/4821cb227c6c8b10419b96674d44ad1d6668a647/flipt-client-browser/src/models.ts#L5) interface to use when requesting flag state. If not provided, a default fetcher using the browser's [`fetch` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) will be used.
+  - `errorStrategy`: The error strategy to use when fetching flag state. If not provided, the client will default to fail. See the [Error Strategies](#error-strategies) section for more information.
+
+### Authentication
+
+The `FliptClient` supports the following authentication strategies:
+
+- No Authentication (default)
+- [Client Token Authentication](https://docs.flipt.io/authentication/using-tokens)
+- [JWT Authentication](https://docs.flipt.io/authentication/using-jwts)
+
+### Error Strategies
+
+The client `errorStrategy` option supports the following error strategies:
+
+- `fail`: The client will throw an error if the flag state cannot be fetched. This is the default behavior.
+- `fallback`: The client will maintain the last known good state and use that state for evaluation in case of an error.
+
+### Custom Fetcher
+
+The `FliptClient` supports custom fetchers. This allows you to fetch flag state from a custom source or override HTTP headers.
+
+The fetcher can be passed in as an argument to the `FliptClient` initializer function.
+
+```typescript
+const client = await FliptClient.init('default', {
+  url: 'http://localhost:8080',
+  authentication: {
+    clientToken
+  },
+  fetcher: customFetcher
+});
+```
+
+The fetcher is a function that takes an optional [`IFetcherOpts`](https://github.com/flipt-io/flipt-client-sdks/blob/4821cb227c6c8b10419b96674d44ad1d6668a647/flipt-client-browser/src/models.ts#L1) argument and returns a `Promise` that resolves to a `Response` object.
+
+## State Management
+
+The `FliptClient` class pulls flag state from the Flipt instance at the `url` provided in the `options` object on instantiation.
+
+To update the flag state, you can call the `refresh` method on the `FliptClient` class.
+
+> [!NOTE]
+> The `refresh` method returns a boolean indicating whether the flag state changed.
+
+```typescript
+// Refresh the flag state
+let changed = await client.refresh();
+
+if (changed) {
+  // Do something
+}
+```
+
+### Auto-Refresh (Node.js Only)
+
+The `FliptClient` class supports auto-refreshing flag state.
+
+To enable auto-refreshing, you can pass the `updateInterval` option to the `FliptClient` initializer function. Under the hood this uses a timer to fetch new flag state at a regular interval.
+
+> [!NOTE]
+> The `updateInterval` option is only supported in Node.js environments.
+
+```typescript
+const client = await FliptClient.init('default', {
+  url: 'http://localhost:8080',
+  updateInterval: 30 // refresh every 30 seconds
+});
+```
+
+Make sure to call the `close` method on the `FliptClient` class once you are done using it to stop the timer and clean up resources.
+
+```typescript
+client.close();
+```
+
+## ETag Support
+
+The default fetcher uses [ETag HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) to reduce the number of requests to the Flipt instance. This is useful in scenarios where the flag state is not frequently updated and you want to reduce the load on the server.
+
+To disable ETag support, you can implement a [custom fetcher](#custom-fetcher) that does not use ETags.
+
+## Development
+
+### WASM
+
+This library uses a WebAssembly (WASM) layer to interact with the Flipt server. It is written in Rust and exposes a JavaScript API using the `wasm-bindgen` and `wasm-pack` tools. We wrap the built WASM layer in a JavaScript API to make it easier to use in a web environment.
+
+### Prerequisites
+
+- [flipt-engine-wasm-js](../flipt-engine-wasm-js)
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm install
+npm test
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to open an issue or submit a Pull Request.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/browser/flipt_engine_wasm_js.d.ts

@@ -0,0 +1,53 @@
+/* tslint:disable */
+/* eslint-disable */
+export class Engine {
+  free(): void;
+  constructor(namespace: string);
+  snapshot(data: any): void;
+  evaluate_boolean(request: any): any;
+  evaluate_variant(request: any): any;
+  evaluate_batch(request: any): any;
+  list_flags(): any;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_engine_free: (a: number, b: number) => void;
+  readonly engine_new: (a: number, b: number) => number;
+  readonly engine_snapshot: (a: number, b: any) => [number, number];
+  readonly engine_evaluate_boolean: (a: number, b: any) => [number, number, number];
+  readonly engine_evaluate_variant: (a: number, b: any) => [number, number, number];
+  readonly engine_evaluate_batch: (a: number, b: any) => [number, number, number];
+  readonly engine_list_flags: (a: number) => [number, number, number];
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_export_4: WebAssembly.Table;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __externref_table_dealloc: (a: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;