k.site.files
Read, write, binary updates, and change logs for site repository files (CmsFile)
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
| KScript API / Server scripts | Current site context; getByUrl/getByFolder require a registered route | Manage CMS file library records (CmsFile), binary bytes, and change logs |
Quick Start
Create a CmsFile metadata record, locate its generated GUID id via all(), and write binary bytes:
js
k.api.post(() => {
const name = "hello-" + Date.now() + ".txt"
k.site.files.add({
name,
extension: ".txt",
contentType: "text/plain"
})
const created = k.site.files.all().find((f) => f.name === name)
k.site.files.updateBinary(created.id, [72, 101, 108, 108, 111])
const afterBinary = k.site.files.get(created.id)
return { id: String(afterBinary.id), size: afterBinary.size }
})Quick Reference
| Method / Property | Description | Returns |
|---|---|---|
add(file) | Adds a CmsFile metadata record without creating a route | void |
updateBinary(nameOrId, binary) | Writes or replaces binary bytes and updates size | void |
all() | Returns all CmsFile records in the site | CmsFile[] |
get(nameOrId) | Retrieves a file by GUID id (filename-only lookup returns null) | CmsFile | null |
getByUrl(url) | Retrieves a file by its registered route URL | CmsFile | null |
getByFolder(folder) | Lists routed files under a folder path (iterate with for...of) | CmsFile[] |
update(file) | Persists metadata updates on a CmsFile | void |
delete(nameOrId) | Deletes a file record by id | void |
getLogs(nameOrId) | Returns change history entries for the file | ChangeLog[] | null |
getByLog(logId) | Restores the file snapshot for a specific log entry ID | CmsFile | null |
Differences from k.file and CMS Console Files
| API / Guide | Purpose |
|---|---|
k.site.files | Manages CmsFile repository records and their change logs |
k.file | Reads and writes files and directories directly on disk storage |
| Files (CMS Console) | Uploads and manages files in the console with automatic route registration |
Runtime Notes
CmsFileassigns a random GUID asidinstead of hashing the filename. Callingk.site.files.get(name)afteradd({ name, ... })returnsnull; locate the record inall()first and pass itsidtoget(id),updateBinary(id, bytes), ordelete(id).k.site.files.add()inserts the repository object without creating a route. Only files with registered routes appear ingetByUrl()orgetByFolder().getByFolder()returns an iterable list at runtime rather than a plain JS array (Array.isArray(...)isfalse); iterate over it withfor...of.
Detailed Methods
add() and updateBinary()
Create a file metadata record, obtain its generated id from all(), and write its binary byte array with updateBinary() (size is updated automatically).
| Parameter | Type | Required | Description |
|---|---|---|---|
file | Partial<CmsFile> | Yes (add) | CmsFile metadata fields (such as name, extension, contentType) |
nameOrId | string | Yes (updateBinary) | GUID id of the CmsFile record |
binary | number[] | Yes (updateBinary) | File binary byte array |
Returns: void
js
k.api.post(() => {
const file = k.site.files.all().find((f) => f.name === "hello.txt")
if (!file) return { found: false }
k.site.files.updateBinary(file.id, [72, 105])
return { size: k.site.files.get(file.id).size }
})all() / get() / getByUrl() / getByFolder()
List site files or look them up by GUID id, registered route URL, or route folder.
| Method | Parameters | Returns | Description |
|---|---|---|---|
all() | None | CmsFile[] | Returns all CmsFile records in the site |
get(nameOrId) | nameOrId: string | CmsFile | null | Retrieves a file by id (passing only a filename returns null) |
getByUrl(url) | url: string | CmsFile | null | Retrieves a file by its registered route URL (for example, "/robots.txt") |
getByFolder(folder) | folder: string | CmsFile[] | Lists routed files under the folder path (iterate using for...of) |
Returns: CmsFile[] or CmsFile | null
js
k.api.get(() => {
const allFiles = k.site.files.all()
const folderFiles = k.site.files.getByFolder("/")
const routedNames = []
for (const file of folderFiles) {
routedNames.push(file.name)
}
return {
totalCount: allFiles.length,
rootRoutedNames: routedNames
}
})update() / delete()
Persist metadata updates or delete a CmsFile record by id.
| Method | Parameters | Returns | Description |
|---|---|---|---|
update(file) | file: CmsFile | void | Persists changes to a CmsFile; change detection tracks name, extension, and binary bytes, so persist contentType updates alongside one of those changes |
delete(nameOrId) | nameOrId: string | void | Deletes a file record by id |
Returns: void
js
k.api.post(() => {
const file = k.site.files.get(k.request.form.id)
if (!file) return { found: false }
file.name = k.request.form.newName
file.contentType = "text/plain; charset=utf-8"
k.site.files.update(file)
return { updated: true, name: k.site.files.get(file.id).name }
})getLogs() / getByLog()
Inspect change logs for a file and restore historical snapshots by log ID.
| Method | Parameters | Returns | Description |
|---|---|---|---|
getLogs(nameOrId) | nameOrId: string | ChangeLog[] | null | Returns change history entries for the file, or null if none exist |
getByLog(logId) | logId: number | CmsFile | null | Restores the file snapshot for a specific log entry ID |
Returns: ChangeLog[] | null or CmsFile | null
js
k.api.get(() => {
const logs = k.site.files.getLogs(k.request.queryString.id)
const firstSnapshot = logs && logs.length ? k.site.files.getByLog(logs[0].logId) : null
return {
logCount: logs ? logs.length : 0,
snapshotName: firstSnapshot ? firstSnapshot.name : null
}
})TypeScript Definitions
ts
interface FileRepository {
add(file: Partial<CmsFile>): void;
all(): CmsFile[];
get(nameOrId: string): CmsFile | null;
getByUrl(url: string): CmsFile | null;
getByFolder(folder: string): CmsFile[];
update(file: CmsFile): void;
updateBinary(nameOrId: string, binary: number[]): void;
delete(nameOrId: string): void;
getLogs(nameOrId: string): ChangeLog[] | null;
getByLog(logId: number): CmsFile | null;
}
interface CmsFile {
id: string;
name: string;
extension: string;
contentType: string;
size: number;
online: boolean;
version: number;
creationDate: Date;
lastModified: Date;
}