@tldraw/utils 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b73a0d46b63f

package/src/lib/warn.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { warnDeprecatedGetter, warnOnce } from './warn'
+
+describe('warning utilities', () => {
+	let consoleSpy: ReturnType<typeof vi.spyOn>
+
+	beforeEach(() => {
+		consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+	})
+
+	afterEach(() => {
+		consoleSpy.mockRestore()
+	})
+
+	describe('warnOnce', () => {
+		it('logs warning message with tldraw prefix', () => {
+			warnOnce('Test warning')
+
+			expect(consoleSpy).toHaveBeenCalledTimes(1)
+			expect(consoleSpy).toHaveBeenCalledWith('[tldraw] Test warning')
+		})
+
+		it('only logs the same message once', () => {
+			warnOnce('Duplicate warning')
+			warnOnce('Duplicate warning')
+			warnOnce('Duplicate warning')
+
+			expect(consoleSpy).toHaveBeenCalledTimes(1)
+		})
+
+		it('logs different messages separately', () => {
+			warnOnce('First warning')
+			warnOnce('Second warning')
+			warnOnce('First warning')
+
+			expect(consoleSpy).toHaveBeenCalledTimes(2)
+		})
+	})
+
+	describe('warnDeprecatedGetter', () => {
+		it('generates correct deprecation warning', () => {
+			warnDeprecatedGetter('viewport')
+
+			expect(consoleSpy).toHaveBeenCalledWith(
+				"[tldraw] Using 'viewport' is deprecated and will be removed in the near future. Please refactor to use 'getViewport' instead."
+			)
+		})
+
+		it('correctly capitalizes property name', () => {
+			warnDeprecatedGetter('camera')
+
+			expect(consoleSpy).toHaveBeenCalledWith(
+				"[tldraw] Using 'camera' is deprecated and will be removed in the near future. Please refactor to use 'getCamera' instead."
+			)
+		})
+
+		it('only shows the same deprecation warning once', () => {
+			warnDeprecatedGetter('uniqueProp')
+			warnDeprecatedGetter('uniqueProp')
+
+			expect(consoleSpy).toHaveBeenCalledTimes(1)
+		})
+	})
+})

package/src/lib/warn.ts

@@ -1,6 +1,25 @@
 const usedWarnings = new Set<string>()
 
-/** @internal */
+/**
+ * Issues a deprecation warning for deprecated getter properties, advising users to use
+ * the equivalent getter method instead. The warning is shown only once per property name.
+ *
+ * @param name - The name of the deprecated property (e.g., 'viewport')
+ *
+ * @example
+ * ```ts
+ * // Inside a class with deprecated property access
+ * get viewport() {
+ *   warnDeprecatedGetter('viewport')
+ *   return this.getViewport()
+ * }
+ *
+ * // Usage will show: "[tldraw] Using 'viewport' is deprecated and will be removed..."
+ * // But only the first time it's accessed
+ * ```
+ *
+ * @internal
+ */
 export function warnDeprecatedGetter(name: string) {
 	warnOnce(
 		`Using '${name}' is deprecated and will be removed in the near future. Please refactor to use 'get${name[0].toLocaleUpperCase()}${name.slice(
@@ -9,7 +28,29 @@ export function warnDeprecatedGetter(name: string) {
 	)
 }
 
-/** @internal */
+/**
+ * Issues a warning message to the console, but only once per unique message.
+ * Subsequent calls with the same message are ignored, preventing console spam.
+ * All messages are prefixed with "[tldraw]".
+ *
+ * @param message - The warning message to display
+ *
+ * @example
+ * ```ts
+ * // Warn about deprecated usage
+ * function oldFunction() {
+ *   warnOnce('oldFunction is deprecated, use newFunction instead')
+ *   // Continue with implementation...
+ * }
+ *
+ * // First call logs: "[tldraw] oldFunction is deprecated, use newFunction instead"
+ * oldFunction() // Shows warning
+ * oldFunction() // No warning (already shown)
+ * oldFunction() // No warning (already shown)
+ * ```
+ *
+ * @internal
+ */
 export function warnOnce(message: string) {
 	if (usedWarnings.has(message)) return