@roku-sdk/common 0.0.0-stage → 2.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roku, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# `@roku-sdk/common`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Low-level building blocks shared by the other RSG SDK packages: the logger, the transaction manager that batches SceneGraph tree updates, string interning, and helpers for Roku structured data. Apps get it as a dependency of `@roku-sdk/rsg-ts` and seldom import it directly.
+
+## Install
+
+```sh
+pnpm add @roku-sdk/common
+```
+
+## Usage
+
+Apps take the logger from `@roku-sdk/rsg-ts`, which re-exports it from this package:
+
+```ts
+import { logger } from "@roku-sdk/rsg-ts";
+
+const log = logger.getLogger("home");
+log.info(() => "home screen mounted");
+```
+
+## Documentation
+
+- [App configuration](../../documentation/core-concepts/app-configuration.md) — setting log levels with `app.logger` in `roku-config.ts`
+- [Exception handling](../../documentation/runtime-and-debugging/exception-handling.md) — reporting uncaught exceptions
+- [Full SDK documentation](../../documentation/README.md)

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import rokuSdkToolsLinterConfig from "@roku-sdk/dev-tools/linter-config/eslint.config.mjs";
+
+export default rokuSdkToolsLinterConfig;

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@roku-sdk/common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.19.0",
+  "description": "Roku TypeScript Common Library",
+  "type": "module",
+  "engines": {
+    "npm": ">=8.5.0",
+    "node": ">=24.0.0"
+  },
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./sd-helper": "./src/sd-helper.ts",
+    "./string-interner": "./src/string-interner.ts",
+    "./transaction": "./src/transaction.ts"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "eslint.config.mjs",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@roku-sdk/interfaces": "2.19.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.4.1",
+    "@roku-sdk/dev-tools": "2.19.0"
+  },
+  "author": "Roku Inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/rokudev/rsg-sdk.git",
+    "directory": "packages/common"
+  },
+  "homepage": "https://gitlab.com/rokudev/rsg-sdk/-/tree/main/packages/common#readme",
+  "bugs": {
+    "url": "https://gitlab.com/rokudev/rsg-sdk/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest",
+    "coverage": "jest --coverage --runInBand --passWithNoTests --testTimeout=60000 --forceExit",
+    "clean": "rm -rf dist",
+    "lint": "eslint --no-error-on-unmatched-pattern \"src/**/*.{ts,tsx,mjs,cjs,js}\""
+  }
 }

package/src/build-variables.ts

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+export function getBuildVariable(variable: string | undefined, fallback: string): string {
+    return typeof variable !== "undefined" && variable !== "" ? variable : fallback;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Roku SDK Common - Main entry point.
+ */
+
+export * from "./sd-helper";
+export * from "./string-interner";
+export * from "./logger";

package/src/logger.ts

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { Logger, LoggerAPI, LoggerRef } from "@roku-sdk/interfaces";
+import { RuntimeInterfaces } from "@roku-sdk/interfaces";
+
+import { getBuildVariable } from "./build-variables";
+
+declare const __BASE_LOG_LEVEL__: string;
+declare const __CURRENT_LOG_LEVEL__: string;
+
+/**
+ * Logger interface with internal loggerRef property
+ */
+interface LoggerWithRef extends Logger {
+    __loggerRef: LoggerRef;
+}
+
+/**
+ * This module provides a logger implementation that routes logs to the
+ * runtime logger API. It supports different log levels and allows for
+ * filtering logs based on the source.
+ */
+
+// Both symbols are registered on `roku` before this module is evaluated, so it is
+// safe to destructure them at module load.
+const { getRuntimeSingletonSync, LogLevel } = roku;
+
+const loggerAPI: LoggerAPI = getRuntimeSingletonSync<LoggerAPI>(RuntimeInterfaces.LoggerAPI) as LoggerAPI;
+
+const baseLogLevelStr = getBuildVariable(__BASE_LOG_LEVEL__, "INFO");
+const currentLogLevelStr = getBuildVariable(__CURRENT_LOG_LEVEL__, "ERROR");
+
+const baseLevel: number = LogLevel[baseLogLevelStr.toUpperCase()] ?? LogLevel.INFO;
+const currentLevel: number = LogLevel[currentLogLevelStr.toUpperCase()] ?? LogLevel.ERROR;
+// TODO: Implement log level update handler
+// loggerAPI.setCurrentLogLevelUpdateHandler((logLevel: LogLevel): void => {
+//     currentLevel = logLevel;
+// });
+
+const logSourceFilter: string | null = null;
+// TODO: Implement log source filter update handler
+// loggerAPI.setLogSourceFilterUpdateHandler((filter: string): void => {
+//     logSourceFilter = filter;
+// });
+
+function createLogger(source: string = ""): LoggerWithRef {
+    const loggerRef = loggerAPI.getLoggerRef(source);
+    const logHandlers: Array<(source: string, level: number, message: string) => void> = [];
+    function logByLevel(
+        loggerRef: LoggerRef,
+        level: number,
+        messageProvider: () => string,
+        logSourceSuffix?: string
+    ): void {
+        // TODO: fix logSourceSuffix regex. Check the performance impact when using regex.
+        if (
+            baseLevel <= level &&
+            currentLevel <= level &&
+            (logSourceFilter === null || source.startsWith(logSourceFilter))
+        ) {
+            const message = messageProvider();
+            loggerAPI.logDevConsole(loggerRef, level, message, logSourceSuffix);
+            for (const handler of logHandlers) {
+                handler(source, level, message);
+            }
+        }
+    }
+    const logger: LoggerWithRef = {
+        trace: (messageProvider: () => string, logSourceSuffix?: string): void => {
+            logByLevel(loggerRef, LogLevel.TRACE, messageProvider, logSourceSuffix);
+        },
+        debug: (messageProvider: () => string, logSourceSuffix?: string): void => {
+            logByLevel(loggerRef, LogLevel.DEBUG, messageProvider, logSourceSuffix);
+        },
+        info: (messageProvider: () => string, logSourceSuffix?: string): void => {
+            logByLevel(loggerRef, LogLevel.INFO, messageProvider, logSourceSuffix);
+        },
+        warn: (messageProvider: () => string, logSourceSuffix?: string): void => {
+            logByLevel(loggerRef, LogLevel.WARN, messageProvider, logSourceSuffix);
+        },
+        error: (messageProvider: () => string, logSourceSuffix?: string): void => {
+            logByLevel(loggerRef, LogLevel.ERROR, messageProvider, logSourceSuffix);
+        },
+        getLogger: (childSource: string): Logger => {
+            return createLogger(source ? `${source}.${childSource}` : childSource);
+        },
+        // Log handler registration methods
+        registerLogHandler: (handler: (source: string, level: number, message: string) => void): void => {
+            logHandlers.push(handler);
+        },
+        unregisterLogHandler: (handler: (source: string, level: number, message: string) => void): void => {
+            const index = logHandlers.indexOf(handler);
+            if (index !== -1) {
+                logHandlers.splice(index, 1);
+            }
+        },
+        __loggerRef: loggerRef
+    };
+
+    logger.trace(() => `Creating logger for source: ${source}`);
+    return logger;
+}
+export const logger = createLogger();

package/src/sd-helper.ts

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { StructuredDataApi, TmArrayRef, TmObjectRef } from "@roku-sdk/interfaces";
+
+import { logger } from "./logger";
+
+const sdLogger = logger.getLogger("sd");
+
+export const createSDHelper = (api: StructuredDataApi) => {
+    const createFullObject = (props: object, tracked = new WeakSet<object>()): TmObjectRef => {
+        // Check for circular references
+        if (tracked.has(props)) {
+            sdLogger.error(() => "Circular reference detected in object");
+            throw new Error("Circular reference detected in object");
+        }
+        tracked.add(props);
+
+        const objRef = api.createObject() as object;
+        Object.entries(props).forEach(([prop, value]) => {
+            switch (typeof value) {
+                case "number":
+                    if (Number.isInteger(value)) {
+                        api.insertInt(objRef, prop, value);
+                    } else {
+                        api.insertFloat(objRef, prop, value);
+                    }
+                    break;
+                case "boolean":
+                    api.insertBool(objRef, prop, value);
+                    break;
+                case "string":
+                    api.insertString(objRef, prop, value);
+                    break;
+                case "object":
+                    if (value === null) {
+                        api.insertNull(objRef, prop);
+                    } else if (Array.isArray(value)) {
+                        const arrayRef = createFullArray(value, tracked);
+                        api.insertArray(objRef, prop, arrayRef);
+                    } else {
+                        const objectRef: TmObjectRef = createFullObject(value, tracked);
+                        api.insertObject(objRef, prop, objectRef);
+                    }
+                    break;
+            }
+        });
+        return objRef;
+    };
+
+    const createFullArray = (array: unknown[], tracked = new WeakSet<object>()): TmArrayRef => {
+        sdLogger.trace(() => `Creating array with ${array.length} elements`);
+        if (tracked.has(array)) {
+            sdLogger.error(() => "Circular reference detected in array");
+            throw new Error("Circular reference detected in array");
+        }
+        tracked.add(array);
+
+        const arrayRef = api.createArray() as object;
+        array.forEach(value => {
+            switch (typeof value) {
+                case "boolean":
+                    api.appendBool(arrayRef, value);
+                    break;
+                case "number":
+                    if (Number.isInteger(value)) {
+                        api.appendInt(arrayRef, value);
+                    } else {
+                        api.appendFloat(arrayRef, value);
+                    }
+                    break;
+                case "string":
+                    api.appendString(arrayRef, value);
+                    break;
+                case "object":
+                    if (value === null) {
+                        api.appendNull(arrayRef);
+                    } else if (Array.isArray(value)) {
+                        const nestedArrayRef = createFullArray(value, tracked);
+                        api.appendArray(arrayRef, nestedArrayRef);
+                    } else {
+                        const objectRef: TmObjectRef = createFullObject(value, tracked);
+                        api.appendObject(arrayRef, objectRef);
+                    }
+                    break;
+            }
+        });
+        return arrayRef;
+    };
+
+    const commit = () => {
+        // No-op: circular reference tracking is scoped per-call via the tracked parameter.
+    };
+
+    return {
+        createFullObject,
+        createFullArray,
+        commit
+    };
+};

package/src/string-interner.ts

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { InternedStringRef, InternStringApi } from "@roku-sdk/interfaces";
+
+let internStringApi: InternStringApi | undefined;
+let reverseMap: Map<InternedStringRef, string> | undefined;
+let forwardMap: Map<string, InternedStringRef> | undefined;
+
+export function registerInternStringApi(i: InternStringApi) {
+    reverseMap = new Map<InternedStringRef, string>();
+    forwardMap = new Map<string, InternedStringRef>();
+    internStringApi = i;
+}
+
+function assertInternStringApi() {
+    if (!internStringApi) {
+        throw new Error("InternStringApi not registered");
+    }
+}
+
+export const stringInterner = {
+    internString: (str: string) => {
+        // TODO: profile this map and move it to the native side if needed
+        assertInternStringApi();
+        let ref = forwardMap!.get(str);
+        if (ref) {
+            return ref;
+        }
+        ref = internStringApi!.internString(str);
+        forwardMap!.set(str, ref);
+        reverseMap!.set(ref, str);
+        return ref;
+    },
+    getStringByInternedRef: (ref: InternedStringRef): string => {
+        assertInternStringApi();
+        const str = reverseMap!.get(ref);
+        if (!str) {
+            throw new Error(`String for ref ${ref} not found`);
+        }
+        return str;
+    }
+};

package/src/transaction.ts

@@ -0,0 +1,79 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { logger } from "@roku-sdk/common";
+import { TransactionApi } from "@roku-sdk/interfaces";
+
+type Transaction =
+    | {
+          inTransaction: boolean;
+      }
+    | undefined;
+
+let transactionApi: TransactionApi | undefined;
+let transaction: Transaction = undefined;
+const precommitHooks: (() => void)[] = [];
+const transactionStartHooks: (() => void)[] = [];
+
+const txLogger = logger.getLogger("tx");
+
+export function registerTransactionApi(incomingTransactionApi: TransactionApi) {
+    transactionApi = incomingTransactionApi;
+}
+
+export function registerPreCommitHook(preCommitHook: () => void) {
+    precommitHooks.push(preCommitHook);
+}
+
+export function registerTransactionStartHook(transactionStartHook: () => void) {
+    transactionStartHooks.push(transactionStartHook);
+}
+let txFlowId: number | undefined;
+
+function getTransactionManager() {
+    const commit = () => {
+        if (!transaction || !transaction.inTransaction) {
+            txLogger.warn(() => "No transaction in progress to commit.");
+            return;
+        }
+        precommitHooks.forEach(hook => {
+            hook();
+        });
+        txLogger.debug(() => "Committing transaction");
+        const txFlowIdToEnd = txFlowId;
+        if (txFlowIdToEnd !== undefined) {
+            roku.perfetto?.flowEvent(txFlowIdToEnd, "transaction.commit");
+        }
+        transactionApi?.end(txFlowIdToEnd);
+        txFlowId = undefined;
+        transaction = undefined;
+    };
+
+    const startTransaction = () => {
+        if (!transaction) {
+            txFlowId = Math.floor(Math.random() * 0x7fffffff);
+            roku.perfetto?.flowEvent(txFlowId, "transaction.start");
+            txLogger.debug(() => "Starting transaction");
+            transactionApi?.start();
+            transactionStartHooks.forEach(hook => {
+                hook();
+            });
+            transaction = { inTransaction: true };
+            Promise.resolve().then(commit);
+        }
+        return transaction;
+    };
+
+    return {
+        startTransaction,
+        inTransaction: () => {
+            return transaction?.inTransaction;
+        },
+        commitEarly: () => {
+            // only call from unit tests
+            commit();
+        }
+    };
+}
+
+export const transactionManager = getTransactionManager();

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "@roku-sdk/dev-tools/typescript-config/tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "types": ["@roku-sdk/interfaces/global"]
+    },
+    "include": ["src/**/*"],
+    "exclude": ["dist", "node_modules"]
+}