@stackframe/stack-shared 2.4.25 → 2.4.26

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @stackframe/stack-shared
 
+## 2.4.26
+
+### Patch Changes
+
+- Improve docs
+- Updated dependencies
+  - @stackframe/stack-sc@2.4.26
+
 ## 2.4.25
 
 ### Patch Changes

package/dist/crud.d.ts

@@ -1,6 +1,15 @@
 import * as yup from 'yup';
 import { NullishCoalesce } from './utils/types';
 export type CrudOperation = "create" | "read" | "update" | "delete";
+declare module 'yup' {
+    interface CustomSchemaMetadata {
+        openapi?: {
+            description?: string;
+            exampleValue?: any;
+            hide?: boolean;
+        };
+    }
+}
 type InnerCrudSchema<CreateSchema extends yup.Schema<any> | undefined = yup.Schema<any> | undefined, ReadSchema extends yup.Schema<any> | undefined = yup.Schema<any> | undefined, UpdateSchema extends yup.Schema<any> | undefined = yup.Schema<any> | undefined, DeleteSchema extends yup.Schema<any> | undefined = yup.Schema<any> | undefined> = {
     createSchema: CreateSchema;
     readSchema: ReadSchema;

package/dist/interface/crud/fields.js

@@ -1,12 +1,12 @@
 import * as yup from "yup";
 import { yupJson } from "../../utils/yup";
-export const projectIdSchema = yup.string().meta({ description: 'Stack dashboard project ID', example: 'project-id' });
-export const userIdSchema = yup.string().meta({ description: 'Unique user identifier', example: 'user-id' });
-export const primaryEmailSchema = yup.string().meta({ description: 'Primary email', example: 'johndoe@email.com' });
-export const primaryEmailVerifiedSchema = yup.boolean().meta({ description: 'Primary email verified', example: true });
-export const userDisplayNameSchema = yup.string().meta({ description: 'User display name', example: 'John Doe' });
-export const selectedTeamIdSchema = yup.string().meta({ description: 'Selected team ID', example: 'team-id' });
-export const profileImageUrlSchema = yup.string().meta({ description: 'Profile image URL', example: 'https://example.com/image.jpg' });
-export const signedUpAtMillisSchema = yup.number().meta({ description: 'Signed up at milliseconds', example: 1630000000000 });
-export const userClientMetadataSchema = yupJson.meta({ description: 'Client metadata. Used as a data store, accessible from the client side', example: { key: 'value' } });
-export const userServerMetadataSchema = yupJson.meta({ description: 'Server metadata. Used as a data store, only accessible from the server side', example: { key: 'value' } });
+export const projectIdSchema = yup.string().meta({ openapi: { description: 'Stack dashboard project ID', exampleValue: 'project-id' } });
+export const userIdSchema = yup.string().meta({ openapi: { description: 'Unique user identifier', exampleValue: 'user-id' } });
+export const primaryEmailSchema = yup.string().meta({ openapi: { description: 'Primary email', exampleValue: 'johndoe@example.com' } });
+export const primaryEmailVerifiedSchema = yup.boolean().meta({ openapi: { description: 'Whether the primary email has been verified to belong to this user', exampleValue: true } });
+export const userDisplayNameSchema = yup.string().meta({ openapi: { description: 'Human-readable display name', exampleValue: 'John Doe' } });
+export const selectedTeamIdSchema = yup.string().meta({ openapi: { description: 'ID of the team currently selected by the user', exampleValue: 'team-id' } });
+export const profileImageUrlSchema = yup.string().meta({ openapi: { description: 'Profile image URL', exampleValue: 'https://example.com/image.jpg' } });
+export const signedUpAtMillisSchema = yup.number().meta({ openapi: { description: 'Signed up at milliseconds', exampleValue: 1630000000000 } });
+export const userClientMetadataSchema = yupJson.meta({ openapi: { description: 'Client metadata. Used as a data store, accessible from the client side', exampleValue: { key: 'value' } } });
+export const userServerMetadataSchema = yupJson.meta({ openapi: { description: 'Server metadata. Used as a data store, only accessible from the server side', exampleValue: { key: 'value' } } });

package/dist/interface/crud/users.js

@@ -20,10 +20,10 @@ export const usersCrudServerReadSchema = yup.object({
     selectedTeamId: fieldSchema.selectedTeamIdSchema.nullable().defined(),
     profileImageUrl: fieldSchema.profileImageUrlSchema.nullable().defined(),
     signedUpAtMillis: fieldSchema.signedUpAtMillisSchema.required(),
-    authMethod: yup.string().oneOf(["credential", "oauth"]).required().meta({ hide: true }), // not used anymore, for backwards compatibility
-    hasPassword: yup.boolean().required().meta({ description: 'Whether the user has a password', example: true }),
-    authWithEmail: yup.boolean().required().meta({ description: 'Whether the user can authenticate with email (email/password and magic link, depending on the project setting on the dashboard)', example: true }),
-    oauthProviders: yup.array(yup.string().required()).required().meta({ description: 'All the OAuth providers connected to this account', example: ['google', 'github'] }),
+    authMethod: yup.string().oneOf(["credential", "oauth"]).required().meta({ openapi: { hide: true } }), // not used anymore, for backwards compatibility
+    hasPassword: yup.boolean().required().meta({ openapi: { description: 'Whether the user has a password', exampleValue: true } }),
+    authWithEmail: yup.boolean().required().meta({ openapi: { description: 'Whether the user can authenticate with their primary e-mail. If set to true, the user can log-in with credentials and/or magic link, if enabled in the project settings.', exampleValue: true } }),
+    oauthProviders: yup.array(yup.string().required()).required().meta({ openapi: { description: 'All the OAuth providers connected to this account', exampleValue: ['google', 'github'] } }),
     clientMetadata: fieldSchema.userClientMetadataSchema,
     serverMetadata: fieldSchema.userServerMetadataSchema,
 }).required();

package/dist/utils/caches.d.ts

@@ -37,7 +37,7 @@ export declare class AsyncCache<D extends any[], T> {
     readonly forceSetCachedValueAsync: (key: D, value: Promise<T>) => ReactPromise<boolean>;
     readonly refresh: (key: D) => Promise<T>;
     readonly invalidate: (key: D) => Promise<T>;
-    readonly onChange: (key: D, callback: (value: T, oldValue: T | undefined) => void) => {
+    readonly onStateChange: (key: D, callback: (value: T, oldValue: T | undefined) => void) => {
         unsubscribe: () => void;
     };
 }
@@ -79,7 +79,7 @@ declare class AsyncValueCache<T> {
     forceSetCachedValueAsync(value: Promise<T>): ReactPromise<boolean>;
     refresh(): Promise<T>;
     invalidate(): Promise<T>;
-    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+    onStateChange(callback: (value: T, oldValue: T | undefined) => void): {
         unsubscribe: () => void;
     };
 }

package/dist/utils/caches.js

@@ -49,7 +49,7 @@ export class AsyncCache {
     forceSetCachedValueAsync = this._createKeyed("forceSetCachedValueAsync");
     refresh = this._createKeyed("refresh");
     invalidate = this._createKeyed("invalidate");
-    onChange = this._createKeyed("onChange");
+    onStateChange = this._createKeyed("onStateChange");
 }
 class AsyncValueCache {
     _options;
@@ -117,7 +117,7 @@ class AsyncValueCache {
         this._pendingPromise = undefined;
         return await this.refresh();
     }
-    onChange(callback) {
+    onStateChange(callback) {
         const storeObj = this._store.onChange(callback);
         if (this._subscriptionsCount++ === 0 && this._options.onSubscribe) {
             const unsubscribe = this._options.onSubscribe(() => {

package/dist/utils/http.d.ts

@@ -0,0 +1,2 @@
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD", "TRACE", "CONNECT"];
+export type HttpMethod = typeof HTTP_METHODS[number];

package/dist/utils/http.js

@@ -0,0 +1 @@
+export const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD", "TRACE", "CONNECT"];

package/dist/utils/promises.d.ts

@@ -1,15 +1,24 @@
 import { Result } from "./results";
-import type { RejectedThenable, FulfilledThenable, PendingThenable } from "react";
-export type ReactPromise<T> = Promise<T> & (RejectedThenable<T> | FulfilledThenable<T> | PendingThenable<T>);
+export type ReactPromise<T> = Promise<T> & ({
+    status: "rejected";
+    reason: unknown;
+} | {
+    status: "fulfilled";
+    value: T;
+} | {
+    status: "pending";
+});
 type Resolve<T> = (value: T) => void;
 type Reject = (reason: unknown) => void;
 export declare function createPromise<T>(callback: (resolve: Resolve<T>, reject: Reject) => void): ReactPromise<T>;
 /**
- * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook.
+ * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook, and caches
+ * the value so that invoking `resolved` twice returns the same promise.
  */
 export declare function resolved<T>(value: T): ReactPromise<T>;
 /**
- * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook.
+ * Like Promise.reject(...), but also adds the status and value properties for use with React's `use` hook, and caches
+ * the value so that invoking `rejected` twice returns the same promise.
  */
 export declare function rejected<T>(reason: unknown): ReactPromise<T>;
 export declare function neverResolve(): ReactPromise<never>;

package/dist/utils/promises.js

@@ -1,4 +1,5 @@
 import { StackAssertionError, captureError } from "./errors";
+import { DependenciesMap } from "./maps";
 import { Result } from "./results";
 import { generateUuid } from "./uuids";
 export function createPromise(callback) {
@@ -29,26 +30,41 @@ export function createPromise(callback) {
         ...status === "rejected" ? { reason: valueOrReason } : {},
     });
 }
+const resolvedCache = new DependenciesMap();
 /**
- * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook.
+ * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook, and caches
+ * the value so that invoking `resolved` twice returns the same promise.
  */
 export function resolved(value) {
-    return Object.assign(Promise.resolve(value), {
+    if (resolvedCache.has([value])) {
+        return resolvedCache.get([value]);
+    }
+    const res = Object.assign(Promise.resolve(value), {
         status: "fulfilled",
         value,
     });
+    resolvedCache.set([value], res);
+    return res;
 }
+const rejectedCache = new DependenciesMap();
 /**
- * Like Promise.resolve(...), but also adds the status and value properties for use with React's `use` hook.
+ * Like Promise.reject(...), but also adds the status and value properties for use with React's `use` hook, and caches
+ * the value so that invoking `rejected` twice returns the same promise.
  */
 export function rejected(reason) {
-    return Object.assign(Promise.reject(reason), {
+    if (rejectedCache.has([reason])) {
+        return rejectedCache.get([reason]);
+    }
+    const res = Object.assign(Promise.reject(reason), {
         status: "rejected",
         reason: reason,
     });
+    rejectedCache.set([reason], res);
+    return res;
 }
+const neverResolvePromise = pending(new Promise(() => { }));
 export function neverResolve() {
-    return pending(new Promise(() => { }));
+    return neverResolvePromise;
 }
 export function pending(promise, options = {}) {
     const res = promise.then(value => {

package/dist/utils/stores.d.ts

@@ -9,6 +9,28 @@ export type ReadonlyStore<T> = {
         unsubscribe: () => void;
     };
 };
+export type AsyncStoreStateChangeCallback<T> = (args: {
+    state: AsyncResult<T>;
+    oldState: AsyncResult<T>;
+    lastOkValue: T | undefined;
+}) => void;
+export type ReadonlyAsyncStore<T> = {
+    isAvailable(): boolean;
+    get(): AsyncResult<T, unknown, void>;
+    getOrWait(): ReactPromise<T>;
+    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onStateChange(callback: AsyncStoreStateChangeCallback<T>): {
+        unsubscribe: () => void;
+    };
+    onceStateChange(callback: AsyncStoreStateChangeCallback<T>): {
+        unsubscribe: () => void;
+    };
+};
 export declare class Store<T> implements ReadonlyStore<T> {
     private _value;
     private readonly _callbacks;
@@ -23,20 +45,9 @@ export declare class Store<T> implements ReadonlyStore<T> {
         unsubscribe: () => void;
     };
 }
-export type ReadonlyAsyncStore<T> = {
-    isAvailable(): boolean;
-    get(): AsyncResult<T, unknown, void>;
-    getOrWait(): ReactPromise<T>;
-    onChange(callback: (value: T, oldValue: T | undefined) => void): {
-        unsubscribe: () => void;
-    };
-    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
-        unsubscribe: () => void;
-    };
-};
 export declare class AsyncStore<T> implements ReadonlyAsyncStore<T> {
     private _isAvailable;
-    private _value;
+    private _mostRecentOkValue;
     private _isRejected;
     private _rejectionError;
     private readonly _waitingRejectFunctions;
@@ -74,7 +85,13 @@ export declare class AsyncStore<T> implements ReadonlyAsyncStore<T> {
     onChange(callback: (value: T, oldValue: T | undefined) => void): {
         unsubscribe: () => void;
     };
+    onStateChange(callback: AsyncStoreStateChangeCallback<T>): {
+        unsubscribe: () => void;
+    };
     onceChange(callback: (value: T, oldValue: T | undefined) => void): {
         unsubscribe: () => void;
     };
+    onceStateChange(callback: AsyncStoreStateChangeCallback<T>): {
+        unsubscribe: () => void;
+    };
 }

package/dist/utils/stores.js

@@ -39,7 +39,7 @@ export class Store {
 }
 export class AsyncStore {
     _isAvailable;
-    _value = undefined;
+    _mostRecentOkValue = undefined;
     _isRejected = false;
     _rejectionError;
     _waitingRejectFunctions = new Map();
@@ -52,7 +52,7 @@ export class AsyncStore {
         }
         else {
             this._isAvailable = true;
-            this._value = args[0];
+            this._mostRecentOkValue = args[0];
         }
     }
     isAvailable() {
@@ -66,7 +66,7 @@ export class AsyncStore {
             return AsyncResult.error(this._rejectionError);
         }
         else if (this.isAvailable()) {
-            return AsyncResult.ok(this._value);
+            return AsyncResult.ok(this._mostRecentOkValue);
         }
         else {
             return AsyncResult.pending();
@@ -78,7 +78,7 @@ export class AsyncStore {
             return rejected(this._rejectionError);
         }
         else if (this.isAvailable()) {
-            return resolved(this._value);
+            return resolved(this._mostRecentOkValue);
         }
         const promise = new Promise((resolve, reject) => {
             this.onceChange((value) => {
@@ -92,17 +92,22 @@ export class AsyncStore {
         return pending(withFinally);
     }
     _setIfLatest(result, curCounter) {
+        const oldState = this.get();
+        const oldValue = this._mostRecentOkValue;
         if (curCounter > this._lastSuccessfulUpdate) {
             switch (result.status) {
                 case "ok": {
-                    if (!this._isAvailable || this._isRejected || this._value !== result.data) {
-                        const oldValue = this._value;
+                    if (!this._isAvailable || this._isRejected || this._mostRecentOkValue !== result.data) {
                         this._lastSuccessfulUpdate = curCounter;
                         this._isAvailable = true;
                         this._isRejected = false;
-                        this._value = result.data;
+                        this._mostRecentOkValue = result.data;
                         this._rejectionError = undefined;
-                        this._callbacks.forEach((callback) => callback(result.data, oldValue));
+                        this._callbacks.forEach((callback) => callback({
+                            state: this.get(),
+                            oldState,
+                            lastOkValue: oldValue,
+                        }));
                         return true;
                     }
                     return false;
@@ -111,9 +116,13 @@ export class AsyncStore {
                     this._lastSuccessfulUpdate = curCounter;
                     this._isAvailable = false;
                     this._isRejected = true;
-                    this._value = undefined;
                     this._rejectionError = result.error;
                     this._waitingRejectFunctions.forEach((reject) => reject(result.error));
+                    this._callbacks.forEach((callback) => callback({
+                        state: this.get(),
+                        oldState,
+                        lastOkValue: oldValue,
+                    }));
                     return true;
                 }
             }
@@ -124,7 +133,7 @@ export class AsyncStore {
         this._setIfLatest(Result.ok(value), ++this._updateCounter);
     }
     update(updater) {
-        const value = updater(this._value);
+        const value = updater(this._mostRecentOkValue);
         this.set(value);
         return value;
     }
@@ -137,7 +146,6 @@ export class AsyncStore {
         this._lastSuccessfulUpdate = ++this._updateCounter;
         this._isAvailable = false;
         this._isRejected = false;
-        this._value = undefined;
         this._rejectionError = undefined;
     }
     setRejected(error) {
@@ -151,6 +159,13 @@ export class AsyncStore {
         return store;
     }
     onChange(callback) {
+        return this.onStateChange(({ state, lastOkValue }) => {
+            if (state.status === "ok") {
+                callback(state.data, lastOkValue);
+            }
+        });
+    }
+    onStateChange(callback) {
         const uuid = generateUuid();
         this._callbacks.set(uuid, callback);
         return {
@@ -166,4 +181,11 @@ export class AsyncStore {
         });
         return { unsubscribe };
     }
+    onceStateChange(callback) {
+        const { unsubscribe } = this.onStateChange((...args) => {
+            unsubscribe();
+            callback(...args);
+        });
+        return { unsubscribe };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.4.25",
+  "version": "2.4.26",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -20,7 +20,7 @@
     }
   },
   "peerDependencies": {
-    "react": "^18.2",
+    "react": ">=18.2",
     "yup": "^1.4.0"
   },
   "peerDependenciesMeta": {
@@ -36,13 +36,15 @@
     "jose": "^5.2.2",
     "oauth4webapi": "^2.10.3",
     "uuid": "^9.0.1",
-    "@stackframe/stack-sc": "2.4.25"
+    "@stackframe/stack-sc": "2.4.26"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",
     "@types/bcrypt": "^5.0.2",
     "@types/react": "^18.2.66",
-    "@types/uuid": "^9.0.8"
+    "@types/uuid": "^9.0.8",
+    "next": "^14.1.0",
+    "react": "^18.2.0"
   },
   "scripts": {
     "build": "tsc",