feat: add deprecation support (#130)

packages/core/src/decorators/deprecated.ts

@@ -0,0 +1,29 @@
+import {deprecate} from '../utils';
+
+/**
+ * Create a deprecated decorator that marks methods as deprecated.
+ */
+export function deprecated(remarks?: string): MethodDecorator {
+  return function (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const name = target.constructor.name
+      ? `${target.constructor.name}.${<string>propertyKey}`
+      : <string>propertyKey;
+    const message = `${name}() has been deprecated.`;
+
+    if (descriptor.value) {
+      descriptor.value = deprecate(descriptor.value, message, remarks);
+    }
+    if (descriptor.get) {
+      descriptor.get = deprecate(descriptor.get, message, remarks);
+    }
+    if (descriptor.set) {
+      descriptor.set = deprecate(descriptor.set, message, remarks);
+    }
+
+    return descriptor;
+  };
+}

packages/core/src/utils/createRef.ts

@@ -4,7 +4,7 @@ export type Reference<TValue> = TValue extends (config: {
   ? TReference
   : {value: TValue};
 
-export function useRef<T>(): Reference<T> {
+export function createRef<T>(): Reference<T> {
   return {} as Reference<T>;
 }
 

packages/core/src/utils/deprecate.ts

@@ -0,0 +1,19 @@
+import {useLogger} from './useProject';
+
+/**
+ * Mark the given function as deprecated.
+ *
+ * @param fn - The function to deprecate.
+ * @param message - The log message.
+ * @param remarks - The optional log remarks.
+ */
+export function deprecate<TArgs extends any[], TThis, TReturn>(
+  fn: (this: TThis, ...args: TArgs) => TReturn,
+  message: string,
+  remarks?: string,
+): (this: TThis, ...args: TArgs) => TReturn {
+  return function (...args) {
+    useLogger().warn({message, remarks, stack: new Error().stack});
+    return fn.apply(this, args);
+  };
+}

packages/core/src/utils/index.ts

@@ -4,15 +4,55 @@
  * @packageDocumentation
  */
 
+import {deprecate} from './deprecate';
+
 export * from './capitalize';
+export * from './deprecate';
 export * from './DetailedError';
 export * from './errorToLog';
 export * from './getContext';
 export * from './range';
 export * from './useProject';
 export * from './useRandom';
-export * from './useRef';
+export * from './createRef';
 export * from './useScene';
 export * from './useThread';
 export * from './useTime';
 export * from './useContext';
+
+import {createRef} from './createRef';
+import {
+  createSignal as createSignalNew,
+  createComputed as createComputedNew,
+} from '../signals';
+
+/**
+ * @deprecated Use {@link createRef} instead.
+ */
+const useRef = deprecate(
+  createRef,
+  'useRef() has been deprecated.',
+  `Use <code>createRef()</code> instead:
+  <pre>import {createRef} from '@motion-canvas/core/lib/utils';</pre>`,
+);
+
+/**
+ * @deprecated Use {@link createSignal} instead.
+ */
+const createSignal = deprecate(
+  createSignalNew,
+  'createSignal() has been moved.',
+  `Import <code>createSignal()</code> from here instead:
+  <pre>import {createSignal} from '@motion-canvas/core/lib/signals';</pre>`,
+);
+
+/**
+ * @deprecated Use {@link createComputed} instead.
+ */
+const createComputed = deprecate(
+  createComputedNew,
+  'createSignal() has been moved.',
+  `Import <code>createComputed()</code> from here instead:
+  <pre>import {createComputed} from '@motion-canvas/core/lib/signals';</pre>`,
+);
+export {useRef, createSignal, createComputed};

packages/examples/src/scenes/quickstart.tsx

@@ -1,10 +1,10 @@
 import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
 import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 import {all} from '@motion-canvas/core/lib/flow';
 
 export default makeScene2D(function* (view) {
-  const myCircle = useRef<Circle>();
+  const myCircle = createRef<Circle>();
 
   view.add(
     <Circle

packages/examples/src/scenes/tweening-color.tsx

@@ -1,11 +1,11 @@
 import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
 import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 import {tween, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
 import {Color} from '@motion-canvas/core/lib/types';
 
 export default makeScene2D(function* (view) {
-  const circle = useRef<Circle>();
+  const circle = createRef<Circle>();
 
   view.add(
     <Circle

packages/examples/src/scenes/tweening-cubic.tsx

@@ -1,10 +1,10 @@
 import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
 import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 import {tween, map, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
 
 export default makeScene2D(function* (view) {
-  const circle = useRef<Circle>();
+  const circle = createRef<Circle>();
 
   view.add(
     <Circle

packages/examples/src/scenes/tweening-linear.tsx

@@ -1,10 +1,10 @@
 import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
 import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 import {tween, map} from '@motion-canvas/core/lib/tweening';
 
 export default makeScene2D(function* (view) {
-  const circle = useRef<Circle>();
+  const circle = createRef<Circle>();
 
   view.add(
     <Circle

packages/examples/src/scenes/tweening-vector.tsx

@@ -1,11 +1,11 @@
 import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
 import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 import {tween, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
 import {Vector2} from '@motion-canvas/core/lib/types';
 
 export default makeScene2D(function* (view) {
-  const circle = useRef<Circle>();
+  const circle = createRef<Circle>();
 
   view.add(
     <Circle

packages/template/src/scenes/example.meta

@@ -5,5 +5,6 @@
       "name": "circle",
       "targetTime": 3
     }
-  ]
+  ],
+  "seed": 3073416149
 }

packages/template/src/scenes/example.tsx

@@ -1,10 +1,10 @@
 import {makeScene2D} from '@motion-canvas/2d';
 import {Circle} from '@motion-canvas/2d/lib/components';
 import {waitFor, waitUntil} from '@motion-canvas/core/lib/flow';
-import {useRef} from '@motion-canvas/core/lib/utils';
+import {createRef} from '@motion-canvas/core/lib/utils';
 
 export default makeScene2D(function* (view) {
-  const circle = useRef<Circle>();
+  const circle = createRef<Circle>();
 
   view.add(
     <Circle ref={circle} width={320} height={320} fill={'lightseagreen'} />,