@nosnibor89/svelte-client-sdk 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# Launch Darkly Svelte SDK
+
+This is a Svelte library for Launch Darkly. It is a wrapper around the official Launch Darkly JavaScript SDK but with a Svelte-friendly API.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Advanced Usage](#advanced-usage)
+  - [Changing user context](#changing-user-context)
+  - [Getting feature flag values](#getting-feature-flag-values)
+    - [Getting immediate flag value](#getting-immediate-flag-value)
+    - [Watching flag value changes](#watching-flag-value-changes)
+    - [Getting all flag values](#getting-all-flag-values)
+
+## Getting started
+
+First, install the package:
+
+```bash
+npm install @launchdarkly/svelte-client-sdk # or use yarn or pnpm
+```
+
+Then, initialize the SDK with your client-side ID using the `LDProvider` component:
+
+```svelte
+<script>
+  import { LDProvider } from '@launchdarkly/svelte-client-sdk';
+  import App from './App.svelte';
+</script>
+
+// Use context relevant to your application
+const context = {
+  user: {
+    key: 'user-key',
+    },
+};
+
+<LDProvider clientID="your-client-side-id" {context}>
+  <App />
+</LDProvider>
+```
+
+Now you can use the `LDFlag` component to conditionally render content based on feature flags:
+
+```svelte
+<script>
+    import { LDFlag } from '@launchdarkly/svelte-client-sdk';
+</script>
+
+<LDFlag flag={'my-feature-flag'}>
+    <div slot="on">
+        <p>this will render if the feature flag is on</p>
+    </div>
+    <div slot="off">
+        <p>this will render if the feature flag is off</p>
+    </div>
+</LDFlag>
+```
+
+## Advanced usage
+
+### Changing user context
+
+You can change the user context by using the `identify` function from the `LD` object:
+
+```svelte
+<script>
+    import { LD } from '@launchdarkly/svelte-client-sdk';
+
+    function handleLogin() {
+        LD.identify({ key: 'new-user-key' });
+    }
+</script>
+
+<button on:click={handleLogin}>Login</button>
+```
+
+### Getting feature flag values
+
+#### Getting immediate flag value
+
+If you need to get the value of a flag at time of evaluation you can use the `useFlag` function:
+
+```svelte
+<script>
+    import { LD } from '@launchdarkly/svelte-client-sdk';
+
+    function handleClick() {
+        const isFeatureFlagOn = LD.useFlag('my-feature-flag', false);
+        console.log(isFeatureFlagOn);
+    }
+</script>
+
+<button on:click={handleClick}>Check flag value</button>
+```
+
+**Note:** Please note that `useFlag` function will return the current value of the flag at the time of evaluation, which means you won't get notified if the flag value changes. This is useful for cases where you need to get the value of a flag at a specific time like a function call. If you need to get notified when the flag value changes, you should use the `LDFlag` component, the `watch` function or the `flags` object depending on your use case.
+
+#### Watching flag value changes
+
+If you need to get notified when a flag value changes you can use the `watch` function. The `watch` function is an instance of [Svelte Store](https://svelte.dev/docs/svelte-store), which means you can use it with the `$` store subscriber syntax or the `subscribe` method. Here is an example of how to use the `watch` function:
+
+```svelte
+<script>
+    import { LD } from '@launchdarkly/svelte-client-sdk';
+
+    $: flagValue = LD.watch('my-feature-flag');
+</script>
+
+<p>{$flagValue}</p>
+```
+
+#### Getting all flag values
+
+If you need to get all flag values you can use the `flags` object. The `flags` object is an instance of [Svelte Store](https://svelte.dev/docs/svelte-store), which means you can use it with the `$` store subscriber syntax or the `subscribe` method. Here is an example of how to use the `flags` object:
+
+```svelte
+<script>
+    import { LD } from '@launchdarkly/svelte-client-sdk';
+
+    $: allFlags = LD.flags;
+</script>
+
+{#each Object.keys($allFlags) as flagName}
+    <p>{flagName}: {$allFlags[flagName]}</p>
+{/each}
+```
+
+## Credits
+
+- Original code by [Robinson Marquez](https://github.com/nosnibor89)

package/dist/LDFlag.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { LD, type LDFlagValue } from './client/SvelteLDClient.js';
+
+  interface LDFlagProps {
+    on: Snippet;
+    off: Snippet;
+    flag: string;
+    matches?: LDFlagValue;
+  }
+
+  let { on, off, flag, matches = true }: LDFlagProps = $props();
+
+  const flagValue = $derived(LD.watch(flag));
+</script>
+
+{#if $flagValue === matches}
+  {@render on()}
+{:else}
+  {@render off()}
+{/if}

package/dist/LDFlag.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from 'svelte';
+import { type LDFlagValue } from './client/SvelteLDClient.js';
+interface LDFlagProps {
+    on: Snippet;
+    off: Snippet;
+    flag: string;
+    matches?: LDFlagValue;
+}
+declare const LdFlag: import("svelte").Component<LDFlagProps, {}, "">;
+type LdFlag = ReturnType<typeof LdFlag>;
+export default LdFlag;

package/dist/client/SvelteLDClient.d.ts

@@ -0,0 +1,19 @@
+import { type Readable, type Writable } from 'svelte/store';
+import type { LDFlagSet, LDOptions } from '@launchdarkly/js-client-sdk';
+import { type LDContext, type LDFlagValue } from '@launchdarkly/js-client-sdk/compat';
+export type { LDContext, LDFlagValue, LDOptions };
+/** Client ID for LaunchDarkly */
+export type LDClientID = string;
+/** Flags for LaunchDarkly */
+export type LDFlags = LDFlagSet;
+/** The LaunchDarkly instance */
+export declare const LD: {
+    identify: (context: LDContext) => Promise<any>;
+    flags: Readable<LDFlagSet>;
+    initialize: (clientId: LDClientID, context: LDContext, options?: LDOptions) => {
+        initializing: Writable<boolean>;
+    };
+    initializing: Readable<boolean>;
+    watch: (flagKey: string) => Readable<LDFlagValue>;
+    useFlag: <TFlag extends LDFlagValue>(flagKey: string, defaultValue: TFlag) => TFlag;
+};

package/dist/client/SvelteLDClient.js

@@ -0,0 +1,107 @@
+import { derived, readonly, writable } from 'svelte/store';
+import { initialize, } from '@launchdarkly/js-client-sdk/compat';
+/**
+ * Checks if the LaunchDarkly client is initialized.
+ * @param {LDClient | undefined} client - The LaunchDarkly client.
+ * @throws {Error} If the client is not initialized.
+ */
+function isClientInitialized(client) {
+    if (!client) {
+        throw new Error('LaunchDarkly client not initialized');
+    }
+}
+/**
+ * Creates a proxy for the given flags object that intercepts access to flag values.
+ * When a flag value is accessed, it checks if the flag key exists in the target object.
+ * If the flag key exists, it returns the variation of the flag from the client.
+ * Otherwise, it returns the current value of the flag.
+ *
+ * @param client - The LaunchDarkly client instance used to get flag variations.
+ * @param flags - The initial flags object to be proxied.
+ * @returns A proxy object that intercepts access to flag values and returns the appropriate variation.
+ */
+function toFlagsProxy(client, flags) {
+    return new Proxy(flags, {
+        get(target, prop, receiver) {
+            const currentValue = Reflect.get(target, prop, receiver);
+            // only process flag keys and ignore symbols and native Object functions
+            if (typeof prop === 'symbol') {
+                return currentValue;
+            }
+            // check if flag key exists
+            const validFlagKey = Object.hasOwn(target, prop);
+            if (!validFlagKey) {
+                return currentValue;
+            }
+            return client.variation(prop, currentValue);
+        },
+    });
+}
+/**
+ * Creates a LaunchDarkly instance.
+ * @returns {Object} The LaunchDarkly instance object.
+ */
+function createLD() {
+    let coreLdClient;
+    const loading = writable(true);
+    const flagsWritable = writable({});
+    /**
+     * Initializes the LaunchDarkly client.
+     * @param {LDClientID} clientId - The client ID.
+     * @param {LDContext} context - The user context.
+     * @param {LDOptions} options - The client options.
+     * @returns {Object} An object with the initialization status store.
+     */
+    function LDInitialize(clientId, context, options) {
+        coreLdClient = initialize(clientId, context, options);
+        coreLdClient.on('ready', () => {
+            loading.set(false);
+            const rawFlags = coreLdClient.allFlags();
+            const allFlags = toFlagsProxy(coreLdClient, rawFlags);
+            flagsWritable.set(allFlags);
+        });
+        coreLdClient.on('change', () => {
+            const rawFlags = coreLdClient.allFlags();
+            const allFlags = toFlagsProxy(coreLdClient, rawFlags);
+            flagsWritable.set(allFlags);
+        });
+        return {
+            initializing: loading,
+        };
+    }
+    /**
+     * Identifies the user context.
+     * @param {LDContext} context - The user context.
+     * @returns {Promise} A promise that resolves when the user is identified.
+     */
+    async function identify(context) {
+        isClientInitialized(coreLdClient);
+        return coreLdClient.identify(context);
+    }
+    /**
+     * Watches a flag for changes.
+     * @param {string} flagKey - The key of the flag to watch.
+     * @returns {Readable<LDFlagsValue>} A readable store of the flag value.
+     */
+    const watch = (flagKey) => derived(flagsWritable, ($flags) => $flags[flagKey]);
+    /**
+     * Gets the current value of a flag.
+     * @param {string} flagKey - The key of the flag to get.
+     * @param {TFlag} defaultValue - The default value of the flag.
+     * @returns {TFlag} The current value of the flag.
+     */
+    function useFlag(flagKey, defaultValue) {
+        isClientInitialized(coreLdClient);
+        return coreLdClient.variation(flagKey, defaultValue);
+    }
+    return {
+        identify,
+        flags: readonly(flagsWritable),
+        initialize: LDInitialize,
+        initializing: readonly(loading),
+        watch,
+        useFlag,
+    };
+}
+/** The LaunchDarkly instance */
+export const LD = createLD();

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export * from './SvelteLDClient';

package/dist/client/index.js

@@ -0,0 +1 @@
+export * from './SvelteLDClient';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * as LDClient from './client/SvelteLDClient.js';
+export type { LDOptions } from './client/SvelteLDClient.js';
+export { default as LDProvider } from './provider/LDProvider.svelte';
+export { default as LDFlag } from './LDFlag.svelte';

package/dist/index.js

@@ -0,0 +1,5 @@
+// Reexport your entry components here
+export * as LDClient from './client/SvelteLDClient.js';
+// Export Components
+export { default as LDProvider } from './provider/LDProvider.svelte';
+export { default as LDFlag } from './LDFlag.svelte';

package/dist/provider/LDProvider.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  import { onMount, type Snippet } from 'svelte';
+  import { LD } from '../client/SvelteLDClient.js';
+  import type { LDClientID, LDContext, LDOptions } from '../client/SvelteLDClient.js';
+
+  interface LDProviderProps {
+    clientID: LDClientID;
+    context: LDContext;
+    options: LDOptions;
+    initializing?: Snippet;
+    children: Snippet;
+  }
+
+  let { clientID, context, initializing, children, options }: LDProviderProps = $props();
+  const { initialize, initializing: isClientInitializing } = LD;
+
+  onMount(() => {
+    initialize(clientID, context, options);
+  });
+</script>
+
+{#if initializing && $isClientInitializing}
+  {@render initializing()}
+{:else}
+  {@render children()}
+{/if}

package/dist/provider/LDProvider.svelte.d.ts

@@ -0,0 +1,12 @@
+import { type Snippet } from 'svelte';
+import type { LDClientID, LDContext, LDOptions } from '../client/SvelteLDClient.js';
+interface LDProviderProps {
+    clientID: LDClientID;
+    context: LDContext;
+    options: LDOptions;
+    initializing?: Snippet;
+    children: Snippet;
+}
+declare const LdProvider: import("svelte").Component<LDProviderProps, {}, "">;
+type LdProvider = ReturnType<typeof LdProvider>;
+export default LdProvider;

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@nosnibor89/svelte-client-sdk",
+  "version": "0.1.0",
+  "description": "Svelte LaunchDarkly SDK",
+  "homepage": "https://github.com/launchdarkly/js-core/tree/main/packages/sdk/svelte",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchdarkly/js-core.git"
+  },
+  "license": "Apache-2.0",
+  "packageManager": "yarn@3.4.1",
+  "keywords": [
+    "launchdarkly",
+    "svelte"
+  ],
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "dev": "vite dev",
+    "build": "vite build && npm run package",
+    "preview": "vite preview",
+    "package": "svelte-kit sync && svelte-package && publint",
+    "prepublishOnly": "npm run package",
+    "lint": "eslint . --ext .ts,.tsx",
+    "prettier": "prettier --write '**/*.@(js|ts|tsx|json|css)' --ignore-path ../../../.prettierignore",
+    "check": "yarn prettier && yarn lint && yarn build && yarn test",
+    "test:unit": "vitest",
+    "test:unit-ui": "vitest --ui",
+    "test:unit-coverage": "vitest --coverage"
+  },
+  "peerDependencies": {
+    "svelte": "^4.0.0"
+  },
+  "dependencies": {
+    "@launchdarkly/js-client-sdk": "^0.3.3",
+    "esm-env": "^1.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^3.0.0",
+    "@sveltejs/kit": "^2.5.27",
+    "@sveltejs/package": "^2.3.7",
+    "@sveltejs/vite-plugin-svelte": "^5.0.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/svelte": "next",
+    "@types/jest": "^29.5.11",
+    "@typescript-eslint/eslint-plugin": "^6.20.0",
+    "@typescript-eslint/parser": "^6.20.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/ui": "^2.1.8",
+    "eslint": "^8.45.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-airbnb-typescript": "^17.1.0",
+    "eslint-config-prettier": "^8.8.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jest": "^27.6.3",
+    "eslint-plugin-prettier": "^5.0.0",
+    "eslint-plugin-svelte": "^2.45.1",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.1.0",
+    "prettier-plugin-svelte": "^3.2.6",
+    "publint": "^0.1.9",
+    "rimraf": "^5.0.5",
+    "svelte": "^5.4.0",
+    "svelte-check": "^4.0.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typedoc": "0.25.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.2",
+    "vitest": "^2.1.8"
+  }
+}