wrestle with types

Author: dummdidumm

packages/svelte/src/motion/private.d.ts

@@ -16,7 +16,13 @@ export interface SpringOpts {
 }
 
 export interface SpringUpdateOpts {
+	/**
+	 * @deprecated Only use this for the spring store; does nothing when set on the Spring class
+	 */
 	hard?: any;
+	/**
+	 * @deprecated Only use this for the spring store; does nothing when set on the Spring class
+	 */
 	soft?: string | number | boolean;
 }
 

packages/svelte/src/motion/public.d.ts

@@ -1,17 +1,83 @@
 import { Readable } from '../store/public.js';
-import { SpringUpdateOpts, TweenedOptions, Updater } from './private.js';
+import { SpringUpdateOpts, TweenedOptions, Updater, SpringOpts } from './private.js';
 
-export interface SpringStore<T> extends Readable<T> {
-	set: (new_value: T, opts?: SpringUpdateOpts) => Promise<void>;
+// TODO we do declaration merging here in order to not have a breaking change (renaming the Spring interface)
+// this means both the Spring class and the Spring interface are merged into one with some things only
+// existing on one side. In Svelte 6, remove the type definition and move the jsdoc onto the class in spring.js
+
+export interface Spring<T> extends Readable<T> {
+	set(new_value: T, opts?: SpringUpdateOpts): Promise<void>;
+	/**
+	 * @deprecated Only exists on the Spring store
+	 */
 	update: (fn: Updater<T>, opts?: SpringUpdateOpts) => Promise<void>;
 	precision: number;
 	damping: number;
 	stiffness: number;
 }
 
-export interface TweenedStore<T> extends Readable<T> {
+/**
+ * A wrapper for a value that behaves in a spring-like fashion. Changes to `spring.target` will cause `spring.current` to
+ * move towards it over time, taking account of the `spring.stiffness` and `spring.damping` parameters.
+ *
+ * ```svelte
+ * <script>
+ * 	import { Spring } from 'svelte/motion';
+ *
+ * 	const spring = new Spring(0);
+ * </script>
+ *
+ * <input type="range" bind:value={spring.target} />
+ * <input type="range" bind:value={spring.current} disabled />
+ * ```
+ */
+export class Spring<T> {
+	constructor(value: T, options?: SpringOpts);
+
+	/**
+	 * Create a spring whose value is bound to the return value of `fn`. This must be called
+	 * inside an effect root (for example, during component initialisation).
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { Spring } from 'svelte/motion';
+	 *
+	 * 	let { number } = $props();
+	 *
+	 * 	const spring = Spring.of(() => number);
+	 * </script>
+	 * ```
+	 */
+	static of<U>(fn: () => U, options?: SpringOpts): Spring<U>;
+
+	/**
+	 * Sets `spring.target` to `value` and returns a `Promise` that resolves if and when `spring.current` catches up to it.
+	 *
+	 * If `options.instant` is `true`, `spring.current` immediately matches `spring.target`.
+	 *
+	 * If `options.preserveMomentum` is provided, the spring will continue on its current trajectory for
+	 * the specified number of milliseconds. This is useful for things like 'fling' gestures.
+	 */
+	set(value: T, options?: { instant?: boolean; preserveMomentum?: number }): Promise<void>;
+
+	damping: number;
+	precision: number;
+	stiffness: number;
+	/**
+	 * The end value of the spring.
+	 * This property only exists on the Spring class.
+	 */
+	target: T;
+	/**
+	 * The current value of the spring.
+	 * This property only exists on the Spring class.
+	 */
+	get current(): T;
+}
+
+export interface Tweened<T> extends Readable<T> {
 	set(value: T, opts?: TweenedOptions<T>): Promise<void>;
 	update(updater: Updater<T>, opts?: TweenedOptions<T>): Promise<void>;
 }
 
-export * from './index.js';
+export { spring, tweened, Tween } from './index.js';

packages/svelte/src/motion/spring.js

@@ -1,6 +1,6 @@
 /** @import { Task } from '#client' */
 /** @import { SpringOpts, SpringUpdateOpts, TickContext } from './private.js' */
-/** @import { SpringStore } from './public.js' */
+/** @import { Spring as SpringStore } from './public.js' */
 import { writable } from '../store/shared/index.js';
 import { loop } from '../internal/client/loop.js';
 import { raf } from '../internal/client/timing.js';
@@ -182,7 +182,7 @@ export class Spring {
 
 	/**
 	 * @param {T} value
-	 * @param {{ stiffness?: number, damping?: number, precision?: number }} [options]
+	 * @param {SpringOpts} [options]
 	 */
 	constructor(value, options = {}) {
 		this.#current.v = this.#target.v = value;
@@ -207,7 +207,7 @@ export class Spring {
 	 * ```
 	 * @template U
 	 * @param {() => U} fn
-	 * @param {{ stiffness?: number, damping?: number, precision?: number }} [options]
+	 * @param {SpringOpts} [options]
 	 */
 	static of(fn, options) {
 		const spring = new Spring(fn(), options);

packages/svelte/src/motion/tweened.js

@@ -1,5 +1,5 @@
 /** @import { Task } from '../internal/client/types' */
-/** @import { TweenedStore } from './public' */
+/** @import { Tweened } from './public' */
 /** @import { TweenedOptions } from './private' */
 import { writable } from '../store/shared/index.js';
 import { raf } from '../internal/client/timing.js';
@@ -82,7 +82,7 @@ function get_interpolator(a, b) {
  * @template T
  * @param {T} [value]
  * @param {TweenedOptions<T>} [defaults]
- * @returns {TweenedStore<T>}
+ * @returns {Tweened<T>}
  */
 export function tweened(value, defaults = {}) {
 	const store = writable(value);

packages/svelte/types/index.d.ts

@@ -1637,15 +1637,81 @@ declare module 'svelte/legacy' {
 }
 
 declare module 'svelte/motion' {
-	export interface SpringStore<T> extends Readable<T> {
-		set: (new_value: T, opts?: SpringUpdateOpts) => Promise<void>;
+	// TODO we do declaration merging here in order to not have a breaking change (renaming the Spring interface)
+	// this means both the Spring class and the Spring interface are merged into one with some things only
+	// existing on one side. In Svelte 6, remove the type definition and move the jsdoc onto the class in spring.js
+
+	export interface Spring<T> extends Readable<T> {
+		set(new_value: T, opts?: SpringUpdateOpts): Promise<void>;
+		/**
+		 * @deprecated Only exists on the Spring store
+		 */
 		update: (fn: Updater<T>, opts?: SpringUpdateOpts) => Promise<void>;
 		precision: number;
 		damping: number;
 		stiffness: number;
 	}
 
-	export interface TweenedStore<T> extends Readable<T> {
+	/**
+	 * A wrapper for a value that behaves in a spring-like fashion. Changes to `spring.target` will cause `spring.current` to
+	 * move towards it over time, taking account of the `spring.stiffness` and `spring.damping` parameters.
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { Spring } from 'svelte/motion';
+	 *
+	 * 	const spring = new Spring(0);
+	 * </script>
+	 *
+	 * <input type="range" bind:value={spring.target} />
+	 * <input type="range" bind:value={spring.current} disabled />
+	 * ```
+	 */
+	export class Spring<T> {
+		constructor(value: T, options?: SpringOpts);
+
+		/**
+		 * Create a spring whose value is bound to the return value of `fn`. This must be called
+		 * inside an effect root (for example, during component initialisation).
+		 *
+		 * ```svelte
+		 * <script>
+		 * 	import { Spring } from 'svelte/motion';
+		 *
+		 * 	let { number } = $props();
+		 *
+		 * 	const spring = Spring.of(() => number);
+		 * </script>
+		 * ```
+		 */
+		static of<U>(fn: () => U, options?: SpringOpts): Spring<U>;
+
+		/**
+		 * Sets `spring.target` to `value` and returns a `Promise` that resolves if and when `spring.current` catches up to it.
+		 *
+		 * If `options.instant` is `true`, `spring.current` immediately matches `spring.target`.
+		 *
+		 * If `options.preserveMomentum` is provided, the spring will continue on its current trajectory for
+		 * the specified number of milliseconds. This is useful for things like 'fling' gestures.
+		 */
+		set(value: T, options?: { instant?: boolean; preserveMomentum?: number }): Promise<void>;
+
+		damping: number;
+		precision: number;
+		stiffness: number;
+		/**
+		 * The end value of the spring.
+		 * This property only exists on the Spring class.
+		 */
+		target: T;
+		/**
+		 * The current value of the spring.
+		 * This property only exists on the Spring class.
+		 */
+		get current(): T;
+	}
+
+	export interface Tweened<T> extends Readable<T> {
 		set(value: T, opts?: TweenedOptions<T>): Promise<void>;
 		update(updater: Updater<T>, opts?: TweenedOptions<T>): Promise<void>;
 	}
@@ -1671,7 +1737,13 @@ declare module 'svelte/motion' {
 	}
 
 	interface SpringUpdateOpts {
+		/**
+		 * @deprecated Only use this for the spring store; does nothing when set on the Spring class
+		 */
 		hard?: any;
+		/**
+		 * @deprecated Only use this for the spring store; does nothing when set on the Spring class
+		 */
 		soft?: string | number | boolean;
 	}
 
@@ -1688,80 +1760,13 @@ declare module 'svelte/motion' {
 	 *
 	 * @deprecated Use [`Spring`](https://svelte.dev/docs/svelte/svelte-motion#Spring) instead
 	 * */
-	export function spring<T = any>(value?: T | undefined, opts?: SpringOpts | undefined): SpringStore<T>;
-	/**
-	 * A wrapper for a value that behaves in a spring-like fashion. Changes to `spring.target` will cause `spring.current` to
-	 * move towards it over time, taking account of the `spring.stiffness` and `spring.damping` parameters.
-	 *
-	 * ```svelte
-	 * <script>
-	 * 	import { Spring } from 'svelte/motion';
-	 *
-	 * 	const spring = new Spring(0);
-	 * </script>
-	 *
-	 * <input type="range" bind:value={spring.target} />
-	 * <input type="range" bind:value={spring.current} disabled />
-	 * ```
-	 * */
-	export class Spring<T> {
-		/**
-		 * Create a spring whose value is bound to the return value of `fn`. This must be called
-		 * inside an effect root (for example, during component initialisation).
-		 *
-		 * ```svelte
-		 * <script>
-		 * 	import { Spring } from 'svelte/motion';
-		 *
-		 * 	let { number } = $props();
-		 *
-		 * 	const spring = Spring.of(() => number);
-		 * </script>
-		 * ```
-		 * 
-		 */
-		static of<U>(fn: () => U, options?: {
-			stiffness?: number;
-			damping?: number;
-			precision?: number;
-		} | undefined): Spring<U>;
-		
-		constructor(value: T, options?: {
-			stiffness?: number;
-			damping?: number;
-			precision?: number;
-		} | undefined);
-		/**
-		 * Sets `spring.target` to `value` and returns a `Promise` that resolves if and when `spring.current` catches up to it.
-		 *
-		 * If `options.instant` is `true`, `spring.current` immediately matches `spring.target`.
-		 *
-		 * If `options.preserveMomentum` is provided, the spring will continue on its current trajectory for
-		 * the specified number of milliseconds. This is useful for things like 'fling' gestures.
-		 *
-		 * 
-		 */
-		set(value: T, options?: {
-			instant?: boolean;
-			preserveMomentum?: number;
-		} | undefined): Promise<unknown>;
-		get current(): T;
-		set damping(v: number);
-		get damping(): number;
-		set precision(v: number);
-		get precision(): number;
-		set stiffness(v: number);
-		get stiffness(): number;
-		set target(v: T);
-		get target(): T;
-		#private;
-	}
+	export function spring<T = any>(value?: T | undefined, opts?: SpringOpts | undefined): Spring<T>;
 	/**
 	 * A tweened store in Svelte is a special type of store that provides smooth transitions between state values over time.
 	 *
 	 * @deprecated Use [`Tween`](https://svelte.dev/docs/svelte/svelte-motion#Tween) instead
 	 * */
-	export function tweened<T>(value?: T | undefined, defaults?: TweenedOptions<T> | undefined): TweenedStore<T>;
+	export function tweened<T>(value?: T | undefined, defaults?: TweenedOptions<T> | undefined): Tweened<T>;
 	/**
 	 * A wrapper for a value that tweens smoothly to its target value. Changes to `tween.target` will cause `tween.current` to
 	 * move towards it over time, taking account of the `delay`, `duration` and `easing` options.