unshift とは何か
unshift は「配列の先頭に要素を追加し、その結果の要素数（length）を返す」メソッドです。ここが重要です：unshift は“破壊的操作”で、元の配列を直接書き換えます。さらに「先頭を動かす」ため、既存の要素をすべて後ろへずらす再配置が起き、配列が大きいほどコストが高くなりがちです。
基本の使い方と戻り値の意味
1件を先頭へ追加する
const a = [10, 20, 30];
const len = a.unshift(5);
console.log(a); // [5, 10, 20, 30]
console.log(len); // 4（現在の要素数）
unshift の戻り値は「追加後の配列の長さ」です。先頭に何が入ったかは a[0] や a.at(0) で参照します。
複数件を一度に追加する
const a = [3, 4];
a.unshift(1, 2);
console.log(a); // [1, 2, 3, 4]
引数をカンマで並べると、左から右の順で先頭側に並びます。ループで1件ずつ追加するより、まとまった追加のほうが読みやすく速いことが多いです。
他の配列を先頭に足す（スプレッドの使いどころ）
別配列の中身を展開して先頭に入れる
const a = [3, 4];
const head = [1, 2];
// 悪い例：入れ子になってしまう
a.unshift(head); // [ [1, 2], 3, 4 ]
// 良い例：要素を展開して追加
a.unshift(...head); // [1, 2, 3, 4]
配列そのものを unshift すると“配列を1要素として”入れてしまいます。要素を展開したいときはスプレッド（…）を使いましょう。
破壊的操作の注意点と“非破壊”の代替
共有参照だと同時に変わる
const a = [10, 20];
const alias = a; // 同じ配列参照
a.unshift(5);
console.log(alias); // [5, 10, 20]（同時に変化）
参照を共有していると、unshift の変更が他所にも波及します。状態管理（React/Vue）や共有前提のデータでは、副作用を避けるため非破壊の代替が安全です。
非破壊で“先頭に追加した新配列”を作る
const a = [10, 20];
const added = [5, ...a]; // スプレッドで前置
// または
const added2 = [5].concat(a); // concat は常に新配列
元配列を壊さずに先頭へ追加した形を得られます。差分検知（再レンダリング）とも相性が良い書き方です。
push と unshift の違い（性能と設計の指針）
末尾操作は一般に高速、先頭操作は高コスト
const a = [1, 2];
a.push(3); // 末尾に追加（高速になりやすい）
a.unshift(0); // 先頭に追加（全体をずらすためコスト増）
大量データや高頻度の更新があるときは、できるだけ末尾操作（push/pop）に寄せる設計が定石です。どうしても先頭に積みたい場合は、別のデータ構造（両端キューなど）も検討しましょう。
“先頭に見せたい”だけなら表示側で工夫
実データは末尾に追加（push）し、表示時に逆順（.slice().reverse() など）で見せると、更新コストを抑えられます。見た目の要件と内部構造を分離すると強いです。
実践例（タイムライン・キューの前置・ログの前詰め）
新着を上に積むタイムライン
let timeline = ["古い投稿2", "古い投稿1"];
const newPost = "新着";
timeline = [newPost, ...timeline]; // 非破壊で先頭に追加
// ["新着", "古い投稿2", "古い投稿1"]
表示の都合で“新しいものが上”なら、非破壊の前置が扱いやすく安全です。
キューに優先タスクを前置する
const queue = ["B", "C"]; // 既存の低優先度
queue.unshift("A-urgent"); // 破壊的に前置
// 直ちに取り出すなら shift と組み合わせる
const next = queue.shift(); // "A-urgent"
“特例で先頭に差し込む”用途は unshift が直感的です。性能要件次第で頻度を調整しましょう。
入力を前詰めで蓄積（先頭へ積む）
const logs = [];
function log(msg) {
logs.unshift(`[${new Date().toISOString()}] ${msg}`);
}
log("起動"); log("接続完了");
// 直近のログが先頭に並ぶ
直近をすぐ見たい用途では unshift が素直です。サイズが大きくなるなら件数制限を合わせて設計します。
よくある落とし穴と回避策
先頭操作の多用でパフォーマンスが落ちることがあります。可能なら末尾中心（push）で設計し、見せ方を工夫して要件を満たしてください。配列そのものを unshift して入れ子になってしまうミスがよくあります。要素を展開するときは必ずスプレッド（…）を使います。参照共有の配列を unshift すると他所の状態が同時に変わり、UIの更新漏れやロジックの破綻につながります。共有が問題になる場面では非破壊スタイル（[value, …arr] や [values].concat(arr)）へ切り替えましょう。
まとめ
unshift は「先頭へ追加して新しい長さを返す」破壊的メソッドです。複数追加は引数を並べ、他配列を足すならスプレッドで展開。性能面では先頭操作はコスト高になりやすいため、可能なら末尾中心へ寄せ、見た目の要件は表示時の並び替えで満たすのが賢明です。共有状態では非破壊の代替（[value, …arr] や concat）を選ぶ。これらを押さえれば、初心者でも“先頭追加”を安全かつ意図通りに扱えます。