Skip to content

k.site.files ​

Read, write, binary updates, and change logs for site repository files (CmsFile)

Execution ContextPrerequisitesTypical Use
KScript API / Server scriptsCurrent site context; getByUrl/getByFolder require a registered routeManage 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 / PropertyDescriptionReturns
add(file)Adds a CmsFile metadata record without creating a routevoid
updateBinary(nameOrId, binary)Writes or replaces binary bytes and updates sizevoid
all()Returns all CmsFile records in the siteCmsFile[]
get(nameOrId)Retrieves a file by GUID id (filename-only lookup returns null)CmsFile | null
getByUrl(url)Retrieves a file by its registered route URLCmsFile | null
getByFolder(folder)Lists routed files under a folder path (iterate with for...of)CmsFile[]
update(file)Persists metadata updates on a CmsFilevoid
delete(nameOrId)Deletes a file record by idvoid
getLogs(nameOrId)Returns change history entries for the fileChangeLog[] | null
getByLog(logId)Restores the file snapshot for a specific log entry IDCmsFile | null

Differences from k.file and CMS Console Files

API / GuidePurpose
k.site.filesManages CmsFile repository records and their change logs
k.fileReads 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

  • CmsFile assigns a random GUID as id instead of hashing the filename. Calling k.site.files.get(name) after add({ name, ... }) returns null; locate the record in all() first and pass its id to get(id), updateBinary(id, bytes), or delete(id).
  • k.site.files.add() inserts the repository object without creating a route. Only files with registered routes appear in getByUrl() or getByFolder().
  • getByFolder() returns an iterable list at runtime rather than a plain JS array (Array.isArray(...) is false); iterate over it with for...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).

ParameterTypeRequiredDescription
filePartial<CmsFile>Yes (add)CmsFile metadata fields (such as name, extension, contentType)
nameOrIdstringYes (updateBinary)GUID id of the CmsFile record
binarynumber[]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.

MethodParametersReturnsDescription
all()NoneCmsFile[]Returns all CmsFile records in the site
get(nameOrId)nameOrId: stringCmsFile | nullRetrieves a file by id (passing only a filename returns null)
getByUrl(url)url: stringCmsFile | nullRetrieves a file by its registered route URL (for example, "/robots.txt")
getByFolder(folder)folder: stringCmsFile[]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.

MethodParametersReturnsDescription
update(file)file: CmsFilevoidPersists changes to a CmsFile; change detection tracks name, extension, and binary bytes, so persist contentType updates alongside one of those changes
delete(nameOrId)nameOrId: stringvoidDeletes 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.

MethodParametersReturnsDescription
getLogs(nameOrId)nameOrId: stringChangeLog[] | nullReturns change history entries for the file, or null if none exist
getByLog(logId)logId: numberCmsFile | nullRestores 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;
}