@apvee/spfx-react-toolkit 1.3.0 → 2.0.0

package/lib/hooks/useSPFxTenantKeyValueStore.d.ts

@@ -0,0 +1,252 @@
+/**
+ * A single item from the tenant key-value store
+ */
+export interface SPFxTenantKeyValueStoreItem<T = unknown> {
+    /** Property key (stored in Title column) */
+    readonly key: string;
+    /** Deserialized property value */
+    readonly value: T;
+    /** Optional description metadata */
+    readonly description: string | undefined;
+    /** SharePoint list item ID (internal use) */
+    readonly id: number;
+}
+/**
+ * Return type for useSPFxTenantKeyValueStore hook
+ */
+export interface SPFxTenantKeyValueStoreResult {
+    /**
+     * Loading state for read operations (`get`, `list`).
+     * True during any active read call.
+     */
+    readonly isLoading: boolean;
+    /**
+     * Last error from read operations.
+     * Cleared on next successful read.
+     */
+    readonly error: Error | undefined;
+    /**
+     * Loading state for write operations (`save`, `remove`).
+     * True during any active write call.
+     */
+    readonly isWriting: boolean;
+    /**
+     * Last error from write operations.
+     * Cleared on next successful write.
+     */
+    readonly writeError: Error | undefined;
+    /**
+     * Whether the current user has permission to write to the store.
+     * Requires Site Collection Administrator role on the tenant app catalog.
+     * Computed asynchronously on first operation.
+     */
+    readonly canWrite: boolean;
+    /**
+     * Computed state: true when the SPHttpClient is available and
+     * the hook is ready to perform operations.
+     */
+    readonly isReady: boolean;
+    /**
+     * Get a single item by key.
+     * Returns undefined if the key does not exist or the list has not been provisioned.
+     *
+     * @param key - Property key to look up
+     * @returns The item with deserialized value, or undefined
+     *
+     * @example
+     * ```tsx
+     * const store = useSPFxTenantKeyValueStore();
+     *
+     * const handleLoad = async () => {
+     *   const item = await store.get<string>('apiEndpoint');
+     *   if (item) {
+     *     console.log(item.value); // "https://api.example.com"
+     *   }
+     * };
+     * ```
+     */
+    readonly get: <T = unknown>(key: string) => Promise<SPFxTenantKeyValueStoreItem<T> | undefined>;
+    /**
+     * List all items in the store.
+     * Returns an empty array if the list has not been provisioned.
+     * Items are sorted by key (Title) ascending.
+     *
+     * @returns Array of all items with deserialized values
+     *
+     * @example
+     * ```tsx
+     * const store = useSPFxTenantKeyValueStore();
+     *
+     * const items = await store.list();
+     * items.forEach(item => {
+     *   console.log(`${item.key}: ${typeof item.value === 'object' ? JSON.stringify(item.value) : item.value}`);
+     * });
+     * ```
+     */
+    readonly list: () => Promise<SPFxTenantKeyValueStoreItem<unknown>[]>;
+    /**
+     * Save (create or update) a key-value pair.
+     * Auto-provisions the hidden list on first write if it doesn't exist.
+     *
+     * Smart serialization:
+     * - Primitives (string, number, boolean, null, bigint) → String(value)
+     * - Date objects → ISO 8601 string
+     * - Objects/arrays → JSON.stringify(value)
+     *
+     * @param key - Property key
+     * @param value - Value to store
+     * @param description - Optional description metadata
+     *
+     * @example
+     * ```tsx
+     * const store = useSPFxTenantKeyValueStore();
+     *
+     * // String value
+     * await store.save<string>('apiEndpoint', 'https://api.example.com', 'Production API');
+     *
+     * // Complex object
+     * await store.save<FeatureFlags>('featureFlags', { enableChat: true, maxUsers: 1000 });
+     * ```
+     */
+    readonly save: <T = unknown>(key: string, value: T, description?: string) => Promise<void>;
+    /**
+     * Remove an item by key.
+     * No-op if the key does not exist or the list has not been provisioned.
+     *
+     * @param key - Property key to remove
+     *
+     * @example
+     * ```tsx
+     * const store = useSPFxTenantKeyValueStore();
+     *
+     * await store.remove('deprecatedSetting');
+     * ```
+     */
+    readonly remove: (key: string) => Promise<void>;
+}
+/**
+ * Hook to manage tenant-wide key-value pairs backed by a hidden SharePoint list.
+ *
+ * The store uses a hidden list named `TenantKeyValueStore` in the tenant app catalog.
+ * The list is auto-provisioned on the first operation (get, list, save, or remove), with:
+ * - Title column: key (indexed, unique)
+ * - Value column: multiline text (Note)
+ * - Description column: multiline text (Note)
+ *
+ * This hook provides an alternative to tenant properties (StorageEntity) for scenarios
+ * requiring read/write access via REST, since Microsoft has blocked the
+ * SetStorageEntity and RemoveStorageEntity REST API endpoints.
+ *
+ * Features:
+ * - CRUD operations (get, list, save, remove) on tenant-scoped key-value data
+ * - Auto-provisioning of the hidden list on first operation (any CRUD call)
+ * - Smart provisioning: ref-based fast path (zero API calls after first check),
+ *   field introspection only when list already exists, Title uniqueness only on creation
+ * - Smart serialization for primitives, Date, and complex objects
+ * - Permission checking (canWrite flag via IsSiteAdmin)
+ * - Unique key enforcement (Indexed + EnforceUniqueValues on Title)
+ * - Concurrent provisioning protection (mutex ref)
+ * - Memory leak safe with mounted state tracking
+ * - Idempotent remove (no-op if key or list doesn't exist)
+ *
+ * Requirements:
+ * - Tenant app catalog must be provisioned
+ * - Read: Any authenticated user
+ * - Write/Remove: Site Collection Administrator role on tenant app catalog site
+ *
+ * @returns Object with loading states, error states, permission flag, and CRUD functions
+ *
+ * @example Basic usage
+ * ```tsx
+ * function TenantConfigPanel() {
+ *   const store = useSPFxTenantKeyValueStore();
+ *
+ *   const [endpoint, setEndpoint] = React.useState<string>('');
+ *
+ *   React.useEffect(() => {
+ *     store.get<string>('apiEndpoint').then(item => {
+ *       if (item) setEndpoint(item.value);
+ *     });
+ *   }, []);
+ *
+ *   const handleSave = async () => {
+ *     await store.save<string>('apiEndpoint', endpoint, 'Production API endpoint');
+ *   };
+ *
+ *   if (!store.isReady) return <Spinner />;
+ *
+ *   return (
+ *     <Stack tokens={{ childrenGap: 10 }}>
+ *       <TextField value={endpoint} onChange={(_, v) => setEndpoint(v ?? '')} />
+ *       <PrimaryButton onClick={handleSave} disabled={store.isWriting}>
+ *         {store.isWriting ? 'Saving...' : 'Save'}
+ *       </PrimaryButton>
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ *
+ * @example Heterogeneous value types
+ * ```tsx
+ * const store = useSPFxTenantKeyValueStore();
+ *
+ * // String
+ * await store.save<string>('appVersion', '2.1.0');
+ * const ver = await store.get<string>('appVersion');
+ *
+ * // Number
+ * await store.save<number>('maxUploadSize', 10485760);
+ * const size = await store.get<number>('maxUploadSize');
+ *
+ * // Complex object
+ * interface FeatureFlags { enableChat: boolean; maxUsers: number; }
+ * await store.save<FeatureFlags>('featureFlags', { enableChat: true, maxUsers: 500 });
+ * const flags = await store.get<FeatureFlags>('featureFlags');
+ * ```
+ *
+ * @example Dashboard listing all properties
+ * ```tsx
+ * function AllPropertiesView() {
+ *   const store = useSPFxTenantKeyValueStore();
+ *   const [items, setItems] = React.useState<SPFxTenantKeyValueStoreItem<unknown>[]>([]);
+ *
+ *   React.useEffect(() => {
+ *     store.list().then(setItems);
+ *   }, []);
+ *
+ *   return (
+ *     <DetailsList
+ *       items={items.map(i => ({
+ *         key: i.key,
+ *         value: typeof i.value === 'object' ? JSON.stringify(i.value) : String(i.value),
+ *         description: i.description ?? '',
+ *       }))}
+ *       columns={[
+ *         { key: 'key', name: 'Key', fieldName: 'key', minWidth: 150 },
+ *         { key: 'value', name: 'Value', fieldName: 'value', minWidth: 200 },
+ *         { key: 'desc', name: 'Description', fieldName: 'description', minWidth: 200 },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Permission-aware UI
+ * ```tsx
+ * function TenantStoreManager() {
+ *   const store = useSPFxTenantKeyValueStore();
+ *
+ *   if (!store.canWrite) {
+ *     return (
+ *       <MessageBar messageBarType={MessageBarType.info}>
+ *         Read-only access. Contact your SharePoint administrator for write permissions.
+ *       </MessageBar>
+ *     );
+ *   }
+ *
+ *   return <EditablePropertyPanel store={store} />;
+ * }
+ * ```
+ */
+export declare function useSPFxTenantKeyValueStore(): SPFxTenantKeyValueStoreResult;
+//# sourceMappingURL=useSPFxTenantKeyValueStore.d.ts.map

package/lib/hooks/useSPFxTenantKeyValueStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxTenantKeyValueStore.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxTenantKeyValueStore.ts"],"names":[],"mappings":"AA0GA;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,CAAC,GAAG,OAAO;IACpD,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,oCAAoC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,SAAS,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEhG;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,2BAA2B,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAErE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3F;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2HG;AACH,wBAAgB,0BAA0B,IAAI,6BAA6B,CAmc1E"}